PHPFUI

PHP Wrapper for the Foundation CSS Framework

PHPFUI, PHP Foundation User Interface, is a modern PHP library that produces HTML formated for Foundation. It does everything you need for a fully functional Foundation page, with the power of an OO language. It currently uses Foundation 6.6.

"I was surprised that people were prepared to write HTML. In my initial requirements for this thing, I had assumed, as an absolute pre-condition, that nobody would have to do HTML or deal with URLs. If you use the original World Wide Web program, you never see a URL or have to deal with HTML. You're presented with the raw information. You then input more information. So you are linking information to information--like using a word processor. That was a surprise to me--that people were prepared to painstakingly write HTML."

Sir Tim Berners-Lee, inventor of the World Wide Web

Using PHPFUI for view output will produce 100% valid HTML and insulate you from future changes to Foundation, your custom HMTL layouts, CSS and JS library changes. You write to an abstract concept (I want a checkbox here), and the library will output a checkbox formatted for Foundation. You can inherit from CheckBox and add your own take on a checkbox, and when the graphic designer decides they have the most awesome checkbox ever, you simply change your CheckBox class, and it is changed on every page system wide.

Don't write HTML by hand!

Usage

namespace PHPFUI;
$page = new Page();
$form = new Form($page);
$fieldset = new FieldSet('A basic input form');
$time = new Input\Time($page, 'time', 'Enter A Time in 15 minute increments');
$time->setRequired();
$date = new Input\Date($page, 'date', 'Pick A Date');
$fieldset->add(new MultiColumn($time, $date));
$fieldset->add(new Input\TextArea('text', 'Enter some text'));
$fieldset->add(new Submit());
$form->add($fieldset);
$page->add($form);
$page->addStyleSheet('/css/styles.css');
echo $page;

Installation Instructions

composer require phpfui/phpfui

Then run update.php from the vendor/phpfui/phpfui directory and supply the path to your public directory / the directory for the various JS and CSS files PHPFUI uses. This will copy all required public files into your public directory. For example:

php vendor/phpfui/phpfui/update.php public/PHPFUI

The PHPFUI library defaults to your-public-directory/PHPFUI, it can be overridden, but it is suggested to use PHPFUI to keep everything in one place. update.php should be run when ever you update PHPFUI.

Versioning

Versioning will match the Foundation versions for Major semantic versions. PHPUI will always support the most recent version of Foundation possible for the Major version. PHPFUI Minor version will include breaking changes and may incorporate changes for the latest version of Foundation. The PHPFUI Patch version will include non breaking changes or additions. So PHPFUI Version 6.0.0 would be the first version of the library, 6.0.1 would be the first patch of PHPFUI. Both should work with any Foundation 6.x version. PHPFUI 6.1.0 will track PHP 7.4 - 8.1, 6.2.0 will track 8.0 - 8.2, but both will still track Foundation 6.x. PHPFUI 7.0.0 would track Foundation 7.x series on currently supported versions of PHP.

Depreciation and Foundation changes

Since major versions of Foundation have in the past depreciated and obsoleted things, PHPFUI will track the latest version of Foundation for class names and functionality. However, when Foundation makes a breaking change or removes something, PHPFUI will continue to support the old functionality as best as possible in the new Foundation framework. Depreciated classes will be put in the \PHPFUI\Vx namespace (where x would be the prior Major Foundation version containing that feature). So if something gets depreciated in a newer version of Foundation, you simply will need to change your code from \PHPFUI\Example to \PHPFUI\V6\Example. The depreciated namespace will only be supported for one Major version of PHPFUI, so it is recommended you migrate off of it in a timely manor.

Full Class Documentation

PHPFUI/InstaDoc

Live Examples

Via PHPFUI/Examples

Unit Testing

Full unit testing using phpfui/html-unit-tester

License

PHPFUI is distributed under the MIT License.

PHP Versions

This library only supports modern versions of PHP which still receive security updates. While we would love to support PHP from the late Ming Dynasty, the advantages of modern PHP versions far out weigh quaint notions of backward compatibility. Time to upgrade.

PHPFUI PayPal Options

There are two ways to interface easily with PayPal. Checkout is recommended as the PayPal PHP wrapper for Express is abandoned.

PayPal Express (not recommended or supported but still works)

$page = new \PHPFUI\Page();
$express = new \PHPFUI\PayPal\Express($page, $yourClientId);
$express->setType('sandbox');
$express->setPaymentUrl($root . '/Paypal/CreatePayment');
$express->setExecuteUrl($root . '/Paypal/AuthorizePayment');
$express->setErrorUrl($root . '/Paypal/ErrorPayment');
$page->add($express);
echo $page;

You will then need to implement the above endpoints using the abandoned paypal/rest-api-sdk-php package.

PayPal Checkout (recommended)

$page = new \PHPFUI\Page();
$container = new \PHPFUI\HTML5Element('div'); // this element's html will be replaced by JavaScript below
$container->add(new \PHPFUI\Header('Pay For Your Order'));
$checkout = new \PHPFUI\PayPal\Checkout($page, $yourClientId);
$head = 'https://www.YourDomain.com/PayPal/';
$executeUrl = $head . 'CompletedPayment';
$createOrderUrl = $head . 'CreateOrder';
$completedUrl = $head . 'Completed';
$cancelledUrl = $head . 'Cancelled';
$errorUrl = $head . 'Error';
$dollar = '$';
$id = $container->getId();
// Example JavaScript, change as needed for your pages
$checkout->setFunctionJavaScript('onCancel', "{$dollar}.post('{$cancelledUrl}',JSON.stringify({orderID:data.orderID}),function(data){{$dollar}('#{$id}').html(data.html)})");
$checkout->setFunctionJavaScript('onError', "{$dollar}.post('{$errorUrl}',JSON.stringify({data:data,actions:actions}),function(data){{$dollar}('#{$id}').html(data.html)})");
$checkout->setFunctionJavaScript('createOrder', "return fetch('{$createOrderUrl}',{method:'post',headers:{'content-type':'application/json'}}).
	then(function(res){return res.json();}).then(function(data){return data.id;})");
$checkout->setFunctionJavaScript('onApprove', "return fetch('{$executeUrl}',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({orderID:data.orderID})}).
	then(function(res){return res.json();}).
	then(function(details){if(details.error==='INSTRUMENT_DECLINED'){return actions.restart();}
	$.post('{$completedUrl}',JSON.stringify({orderID:data.orderID}),function(data){{$dollar}('#{$id}').html(data.html)})})");
$container->add($checkout);
$page->add($container);
echo $page;

You will then need to implement the above endpoints using paypal/paypal-checkout-sdk package.

You can use the PHPFUI\PayPal classes to format the JSON response. They are fully type checked and bounded to avoid stupid errors.

Example createOrder

namespace \PHPFUI\PayPal;

$order = new Order('CAPTURE');

$applicationContent = new ApplicationContent();
$applicationContent->brand_name = 'EXAMPLE INC';
$applicationContent->locale = 'en-US';
$applicationContent->landing_page = 'BILLING';
$applicationContent->shipping_preferences = 'SET_PROVIDED_ADDRESS';
$applicationContent->user_action = 'PAY_NOW';
$order->setApplicationContent($applicationContent);

$purchase_unit = new PurchaseUnit();
$purchase_unit->reference_id = 'PUHF';
$purchase_unit->description = 'Sporting Goods';
$purchase_unit->custom_id = 'CUST-HighFashions';
$purchase_unit->soft_descriptor = 'HighFashions';
$amount = new Amount();
$amount->setCurrency(new Currency(220.00));
$breakdown = new Breakdown();
$breakdown->item_total = new Currency(180.00);
$breakdown->shipping = new Currency(20.00);
$breakdown->handling = new Currency(10.00);
$breakdown->tax_total = new Currency(20.00);
$breakdown->shipping_discount = new Currency(10.00);

$amount->breakdown = $breakdown;
$purchase_unit->amount = $amount;

$shipping = new Shipping();
$shipping->method = 'United States Postal Service';
$address = new Address();
$address->address_line_1 = '123 Townsend St';
$address->address_line_2 = 'Floor 6';
$address->admin_area_2 = 'San Francisco';
$address->admin_area_1 = 'CA';
$address->postal_code = '94107';
$address->country_code = 'US';
$shipping->address = $address;
$purchase_unit->shipping = $shipping;

$item = new Item('T-Shirt', 1, new Currency(90.00));
$item->description = 'Green XL';
$item->sku = 'sku01';
$item->tax = new Currency(10.00);
$item->category = 'PHYSICAL_GOODS';
$purchase_unit->addItem($item);

$item = new Item('Shoes', 2, new Currency(45.00));
$item->description = 'Running, Size 10.5';
$item->sku = 'sku02';
$item->tax = new Currency(5.00);
$item->category = 'PHYSICAL_GOODS';
$purchase_unit->addItem($item);

$order->addPurchaseUnit($purchase_unit);

$request = new \PayPalCheckoutSdk\Orders\OrdersCreateRequest();
$request->prefer('return=representation');
$request->body = $order->getData();
$env = new \PayPalCheckoutSdk\Core\SandboxEnvironment($yourClientId, $yourSecret);
$client = new \PayPalCheckoutSdk\Core\PayPalHttpClient($env);
$response = $client->execute($request);
$page = new \PHPFUI\Page();
$page->setRawResponse(json_encode($response->result, JSON_PRETTY_PRINT));
echo $page;

Example onApprove

You will probably want to save the generated orderId from the above and check it here for additional validation. You will also want to do what ever processing you need to save and process the payment.

$json = json_decode(file_get_contents('php://input'), true);
$request = new \PayPalCheckoutSdk\Orders\OrdersCaptureRequest($json['orderID']);
$request->prefer('return=representation');
$env = new \PayPalCheckoutSdk\Core\SandboxEnvironment($yourClientId, $yourSecret);
$client = new \PayPalCheckoutSdk\Core\PayPalHttpClient($env);
$response = $client->execute($request);
$result = $response->result;
$txn = $result->purchase_units[0]->payments->captures[0]->id;
$status = $result->purchase_units[0]->payments->captures[0]->status;
$payment_amount = $result->purchase_units[0]->payments->captures[0]->amount->value;
$page = new \PHPFUI\Page();
$page->setRawResponse(json_encode($response->result, JSON_PRETTY_PRINT));
echo $page;

Example Completed, onError or onCancel

Return the HTML that will be use to replace the original PayPal buttons. You can also pass other things back as needed.

$json = json_decode(file_get_contents('php://input'), true);
$container = new \PHPFUI\Container();
$container->add(new \PHPFUI\Header('Thanks for your PayPal Payment'));
$pre = new \PHPFUI\HTML5Element('pre');
$pre->add(print_r($json, 1));
$container->add($pre);
$response = ['html' => "{$container}"];
$page = new \PHPFUI\Page();
$page->setRawResponse(json_encode($response, JSON_PRETTY_PRINT));
echo $page;

Package Documentation