Download the PHP package phery/phery without Composer

PHP + jQuery + AJAX + File upload

Enter phery.js, the swiss army knife of jQuery and PHP

Highlights

• Subscribe on the client and publish on the server, and execute functions bound to elements fast and easy, within their own contexts.
• Declarative and unobstrusive HTML instead of imperative Javascript
• AJAX file uploads for good browsers with no effort, just make the form pheryfied
• Really small footprint, no external dependencies beside jQuery
• Coded with performance and security in mind
• Code, server and client side, completely commented, all methods have docs
• Javascript config locking and Object.freeze to make it harder for tampering
• The same way you write jQuery in Javascript, you write it in PHP
• Turns static Javascript app code into a dynamic language with a chainable query builder style
• Unit tested, mocha for the javascript and PHPUnit_Selenium for PHP
• Support for old, new and upcoming jQuery functions out of the box, since nothing is hard coded
• You may nest PheryResponses the way you would with jQuery
• You may set Javascript callbacks directly from PHP
• You can call jQuery plugin functions directly from PHP (think colorbox for example)
• Built-in CSRF mechanism that makes each AJAX request signed
• Inline conditional execution using unless or incase
• Access or call any Javascript code on the page, set/unset variables, add functions to the page on-the-fly
• Plays really well as the transport for client-side frameworks and libraries as such AngularJS, Ember.js, Knockout.js, ExtJS, Backbone

Example code

Check the a lot of examples and code at http://phery-php-ajax.net/demo.php

Introduction

This library is PSR-4 Compatible

The main goal of this library is to make jQuery (and Javascript), be completely dynamic instead of static and unchangeable code, returning commands on-the-fly from the server and execute them in order on the client, while still manipulating the DOM and dealing with callbacks.

This library unleashes everything you expect from an AJAX library, with nested responses, merging and unmerging responses, direct access to the DOM element that is making the AJAX call. It's loosely based on jquery-ujs for Rails concept.

It's a straightforward and powerful AJAX library with direct integration and mapping of all jQuery functions in PHP, the mapping is extended to custom functions set by $.fn, can create elements just like $('<div/>') does, as phery.js creates a seamless integration with jQuery functions, through AJAX to PHP functions, as you can call a PHP function using AJAX

All jQuery functions listed in here are available to call directly from the PheryResponse class: http://api.jquery.com/ including any new versions of jQuery that comes out, its compatible with jQuery forever, since there are no hardcoded jQuery functions in the PHP code. No need to update phery.js, as it will continue to work with future versions of jQuery automatically (unless jQuery change anything in core that breaks any existing function).

phery.js uses HTML5 data attributes to achieve this, and no additional libraries (besides jQuery, since it's a plugin) are needed, even for Internet Explorer. Links and forms will still be able to send GET/POST requests and function properly without when no javascript isn't enabled, because it doesn't use obtrusive techniques and relies on event delegation.

Strict standards for PHP 5.3+ and advised to use jQuery 1.8+. Being just one PHP file, and one javascript file, it's pretty easy to carry around or to implement in PHP auto-load scenarios, plus it's really FAST! Average processing time is around 2ms with vanilla PHP, according to Firebug and in the demo page

The magic_quotes_gpc directive is DEPRECATED in 5.3 and REMOVED in 5.4, since you are always 100% responsible for the security of your data, so escape your text accordingly to avoid SQL injection or XSS attacks.

All AJAX requests are sent as POST only, so it can still interact with GET query strings, like paginations and such (?p=1 / ?p=2 / ...).

The code is mostly commented using phpDoc and jsDoc, for a steep learning curve, using doc-enabled IDEs, like Netbeans, Aptana, Phpstorm and Eclipse based IDEs. Also, most of the important and most used functions in jQuery were added as phpDoc (from http://api.jquery.com/), as a magic method of the PheryResponse class .

What do I need?

• PHP 5.3.3+
• jQuery 1.8+
• Firefox 3.6+, IE 9+, Chrome 12+, Safari 7+

Upcoming

• Mocha unit tests for the Javascript side running against multiple versions of jQuery on the repo
• PHPUnit_Selenium test cases for Javascript/PHP testing sources on the repo

Upgrading from < 2.4.0

Version 2.4.0 isn't a drop-in replacement because of some changes, so you might need to update your code

• All the calls to PheryResponse::factory()->this() must be called to PheryResponse::factory()->this
• All the calls to PheryResponse::factory()->jquery()->somemethod() must be called to PheryResponse::factory()->jquery->somemethod()
• If you are using jQuery >=1.9, some functions were removed from the jQuery core, so fix your code accordingly
• If you found yourself adding data-remote manually to HTML elements like <a data-remote="remote">stuff</a>, you have to fix it manually or use the prefered way Phery::link_to, since the data-remote is now data-phery-remote
• The same with data-confirm, you have to fix it manually or use the prefered way Phery::link_to, since the data-confirm is now data-phery-confirm

Full PHP API Documentation

http://phery-php-ajax.net/docs/

Installation

Install Phery with Composer:

Documentation

It's really simple as:

When clicking a link with data-phery-remote, it will automatically call the "function_name" callback, that will return a response and apply everything automagically

Complete class declarations and functions at http://phery-php-ajax.net/docs/

PHP server-side

There is an special global setting to make phery.js to not expose information about your server on exceptions, that is a static configuration Phery::$expose_paths, which is set to false by default. If you want to know exactly which file is generating the exception, use Phery::$expose_paths = true;

Phery - The main class, that should be reused everywhere (singleton style), but you can create many instances just fine

Phery::instance()->callback(array('before' => array(), 'after' => array()))

Add a callback that will execute in all functions that are registered using Phery::instance()->set(), and can be any number of callbacks, useful when you're going to execute the same task for all AJAX requests.

Phery::instance()->data(...)

Add any additional data, that will be accessible to either process functions or callback

Phery::args(array $data, $encoding = 'UTF-8')

Encode arguments that phery can understand (json_encode'd) that goes inside . Doing it by hand can have some unwanted side effects, since the JSON must be perfectly made

Phery::is_ajax($is_phery = false)

Returns a boolean, checks if it's a AJAX request (checks for X-Requested-With header). Set $is_phery to true to check specifically for phery.js call

Phery::error_handler($errno, $errstr, $errfile, $errline)

Public static function that throws a exception and return a PheryResponse with the exception. May be registered as a handler using set_error_handler('Phery::error_handler', E_ALL); for example

Phery::shutdown_handler()

Public static function that should be used only with register_shutdown_function('Phery::shutdown_handler'); having no other useful meaning

Phery::respond($response, $echo = false)

Static function that makes it easy to return a PheryResponse anywhere.

Phery::instance()->views(array())

Set up the rendering functions for phery.view() on Javascript side. Automates the rendering of partials, and you may apply transitions between pages. Ajaxifying your website reduces the round trip by 60% less total content size, even less with GZIP

Phery::instance()->process($last_call = true)

Takes just one parameter, $last_call, in case you want to call process() again later, with a different set. last_call won't allow the process to return until you call it again or exit the code inside a callback function.

Phery::instance()->config(array())

Set configuration for the current instance of phery. Passed as an associative array, and can be passed when creating a new instance.

• exit_allowed => true Defaults to true, stop further script execution. Set this to false on frameworks that need to do proper cleanup and/or event triggering

• exceptions => false Throw exceptions on errors

• set_always_available => false By default, the function Phery::instance()->set() will only register functions when the current request is an AJAX call, to save resources. In order to use Phery::instance()->get_function() anytime, you need to set this config value to true

• error_reporting => false|E_ALL|E_DEPRECATED|... Error reporting temporarily using error_reporting(). 'false' disables the error_reporting and wont try to catch any error. Anything else than false will throw a PheryResponse->exception() with the message, code, line and file

• csrf => false Enable CSRF protection, uses PHP sessions. The meta tag MUST be inside the head of your page using ``

• return => false Setting this to true will make Phery::instance()->process() method return the answer (and won't exit the code, overrides exit_allowed), so you may do your cleanups and set the answer where you may please

Phery::instance($config = null)

Singleton static method, ensures just one instance of phery.js, this is prefered over creating multiple instances

Phery::instance()->set(array $functions)

Register the functions that will be triggered by AJAX calls. The key is the function alias, the value is the function itself.

Callback/response function comprises of:

Phery::instance()->unset_function($name)

Unset any previously function set with Phery::instance()->set()

Phery::instance()->csrf($check = false)

Create a new token inside PHP session to prevent CSRF attacks, and return as a <meta> tag. Need to enable CSRF setting with config()

Phery::factory(array $config = null)

Creates a new instance of phery.js, that is chainable

Phery::link_to($title, $function, array $attributes = array(), Phery $phery = null, $no_close = false)

Helper static method to create any element with AJAX enabled. Check sources, phpDocs or an IDE code hinting for a better scoop and detailed info http://phery-php-ajax.net/docs/class-Phery.html#_link_to When creating this element, if you use data-phery-related, you can merge multiple forms in one AJAX call

You may create a non-clickable container that hold many elements that may serve as a template. Using link_to as the following:

Phery::form_for($action, $function, array $attributes = array(), Phery $phery = null)

Helper static method to open a form that will be able to execute AJAX submits. Check sources, phpDocs or an IDE code hinting for a better scoop and detailed info http://phery-php-ajax.net/docs/class-Phery.html#_form_for When creating this element, if you use data-phery-related, you can merge multiple forms in one AJAX call

Phery::select_for($function, $items, array $attributes = array(), Phery $phery = null)

Helper static method to display a select element that make AJAX calls on change. http://phery-php-ajax.net/docs/class-Phery.html#_select_for When creating this element, if you use data-phery-related, you can merge multiple forms in one AJAX call

Phery::coalesce(...)

Helper static method that returns the first non null/false/0 item (taken from MYSQL COALESCE). Notice that depending on error reporting, some notices will be THROWN, to make sure use @ in front of the variable

PheryResponse - Used as a return value to any function called using AJAX

Check the code completion using an IDE for a better view of the functions, read the source or check the examples Any jQuery function can be called through PheryResponse, even custom ones, defined through $.fn.extend or $.function Since version 2.0, you may nest PheryResponses, and the this property was added, to access the calling element (or form) directly from PHP http://phery-php-ajax.net/docs/class-PheryResponse.html

A few special attributes:

• Responses can be serialized and saved on the database without any special effort
• You may pass functions and nest many responses, either as setters or getters (check the demo.php file)
• The method chaining nature of the response make it easy to return, in any order, everything you need
• You can execute next-in-chain methods conditionally using unless and incase (act as if not and if)
• ->this-> refer to the calling DOM element, like doing $(this).
• ->window-> translates to $(window).
• ->document-> translate to $(document).
• ->jquery-> translate to $.
• ->anyobj-> makes you able to access ANY global object and call methods on it. For example $r->my_obj->execute('param1'); will do a window.my_obj.execute('param1');. It's a shortcut to the PheryResponse->access() method
• PheryResponse->call and PheryResponse->apply sets the context (this) of the called function to the passed object, for example PheryResponse->call(array('obj', 'method')), the this inside method is obj

PheryFunction - On-the-fly function callbacks

This class allows you to pass a string that will be made into an anonymous function, useful for jQuery functions that needs a callback. You may bind parameters and variables that will be replaced inside the function, like:

Another example:

PheryException - Exceptions that are thrown by phery, when enabled to do so, with some descriptive errors

Check the code completion using an IDE for a better view of the functions, read the source or check the examples http://phery-php-ajax.net/demo.php

Javascript client-side

Special selectors

There are three jQuery helper selectors: :phery-remote, that return elements if they have phery remote functions attached, :phery-confirm if the element got any confirmation before click/submit and :phery-view, to determine if the calling element belongs to the view You may check elements that have phery.js enabled using

or selecting all the elements for a class

Or combine them in the remotes function, to execute them in order

$('form').serializeForm(opts)

Generate an object serialized with unlimited depth from forms. Opts can be defined as:

• disabled: boolean, process disabled form elements, defaults to false
• all: boolean, include all elements from a form, including null ones, assigning an integer to the item, defaults to false
• empty: boolean, setting to false will skip empty fields (won't be submitted), setting to true will submit empty key:values pairs, including non checked radio and checkboxes, this overrides "all" setting, defaults to true
• files_apart: boolean, Return an object comprising of {'files': {}, 'inputs': {}}, so form inputs doesn't get mixed with file inputs

This function can also be called directly on select, input (all types) and textarea DOM elements, and the transformations will happen automatically

• A form like:

• will generate an object like:

• if the files_apart is set to true :

$('form').reset()

An helper function that has been long missing from jQuery, to simply reset a form and remove all values from it. Can reset multiple forms at once

$(el).phery()

Returns functions associated with phery.js and the element, they extend the $.fn part of jQuery

$(el).phery('remote', [args])

$(el).phery().remote(args)

Trigger the AJAX call, can pass an additional object. Executes the phery.js data associated with the element. Returns the jQuery AJAX object. The data that is passed to the function will overwrite the variables in the object if the have the same name.

An element created with

When calling e.g: $('a').phery('remote', {'append': false});, the append setting will be rewritten, so be careful when passing temporary arguments to the phery('remote') function. All arguments passed using this function are temporary, they don't get stored in the element, even if the value already exists in the element.

$(el).phery().data(key, value);

$(el).phery('data', key, value);

If this function is called without any arguments, will return all phery data associated with the current element.

$(el).phery().exception(msg, data);

$(el).phery('exception', msg, data);

Trigger the exception handler on the element. Returns the current jQuery elements.

$(el).phery().append_args(...);

$(el).phery('append_args', ...);

Append arguments to the current element. The initial value will decide how the parameters will behave in the future. These changes are not temporary, they last as long the DOM element is on the page This function return the phery() of the element, so you may chain remote()

$(el).phery().set_args(...);

$(el).phery('set_args', ...);

Set arguments to the current element. Overwrites any data previously set. It cannot use single values, any string, number, etc will become a [value] It's better to always pass preferably an object, or at least an array. These changes are not temporary, they last as long the DOM element is on the page This function return the phery() of the element, so you may chain remote()

$(el).phery().get_args(...);

$(el).phery('get_args');

Get data arguments of the current element.

$(el).phery().make();

$(el).phery('make');

Add phery.js to the selected element, set the AJAX function name and you may pass arguments. Returns the current jQuery elements.

It will make the a call test with arguments {loaded: true}

$(el).phery().remove();

$(el).phery('remove');

Clean up the element, and remove it from the DOM. It removes all data before so it won't memory leak on IE

$(el).phery().inprogress();

$(el).phery('inprogress');

Returns boolean if there's already an AJAX call going on. You may prevent double form submissions for example checking if element is in progress, returning false if there's already another in progress

You may disabled it automatically per element, when creating the element with Phery::link_to or Phery::form_for passing array(only => true) or you may set it programatically using el.phery('data', 'only', true); Notice that animations and asynchronous functions won't count as "in progress".

$(el).phery().subscribe({'name': function(){}), remove);

$(el).phery('subscribe', {'name': function(){}}, remove);

Subscribe to a topic and receive data from the server (or other part of the client code through publish) Internally, it uses jQuery.Callbacks, so they will fire in order they were added.

if you set the remove argument to true, the callback will be removed

$(el).phery().publish('name', args);

$(el).phery('publish', 'name', args);

Publish a message on the topic with arguments (that are optional). The args passed must be an array (think jQuery trigger)

$(el).phery().one(args);

$(el).phery('one', args);

Executes the phery.remote on only one element from the jQuery element stack and returns a promise (like phery.remote does)

$(el).phery().unmake(unbind = false);

$(el).phery('unmake');

Remove phery.js AJAX functions on the select elements. Setting the unbind parameter to true will also unbind the phery.js events that were previously set Returns the current jQuery elements.

phery.subscribe(name, args)

Create a subscription without attaching to any DOM elements. Takes almost the same parameters as phery.remote

phery.timer(element, miliseconds)

Make an ajax call automatically every miliseconds. It uses setTimeout instead of setInterval, returns two functions to start or stop the timer. You can't pass a phery.remote() call directly to this function, it need to be either a DOM element or in form of an array that you would pass in phery.remotes

phery.broadcast(name, args)

Broadcast a topic to all elements that has this topic subscribed. The args must be passed as an array.

phery.remotes(array)

Call a series of AJAX calls in order, waiting for the last call to finish. Returns a promise for all the queued calls, so you can watch it with progress, and use then (or a chain of then). Calls will be made in sequence regardless if they were successiful or not

An array of array of arguments, the same you'd call phery.remote with.

You may also pass a jQuery set of phery.js-ready elements

This isn't the same as doing $('.containers:not(.loaded)').phery('remote'), because in that case elements will be called at once, asynchronously, with no progress or any feedback. Also you may observe the progress of the functions using the progress as part of the promise:

phery.json(function_name, args, callback)

Calls an AJAX function, pass some args if needed (pass null for no arguments) and the callback, containing a function(data){} Usage:

It's a shorthand for the following code:

phery.element(function_name, attrs)

Shorthand for phery.remote('function', null, attrs, false) to create reusable AJAX elements with their own element that isn't bound to the DOM (but may eventually be appended to the DOM)

• function_name: string, name of the alias defined in Phery::instance()->set() inside PHP
• attr: object, set any additional information about the DOM element, usually for setting another href to it. eg: {href: '/some/other/url?p=1'}

phery.remote(function_name, args, attr, direct_call)

Calls an AJAX function directly, without binding to any existing elements, the DOM element is created and removed on-the-fly If directCall is false, it will return a jQuery a element, if not, it will return an jqXHR object

• function_name: string, name of the alias defined in Phery::instance()->set() inside PHP
• args: object or array or variable, the best practice is to pass an object, since it can be easily accessed later through PHP, but any kind of parameter can be passed, from strings, ints, floats, and can also be null (won't be passed through ajax)
• attr: object, set any additional information about the DOM element, usually for setting another href to it. eg: {href: '/some/other/url?p=1'}
• direct_call: boolean, defaults to true, setting this to false, will return the created DOM element (invisible to the user) and can have events bound to it, but will be removed right after the response is processed

When setting direct_call to false, the returned element can be reused many times, using phery('remote'), to explicitly remove it, you need to call phery('remove')

If you wish to remove it as soon as the call ends, pass in the attr parameter, the temp option:

If direct_call is undefined or true (the default) the element is removed and cleaned after each remote call.

Options and global and element events

Global events will always trigger, and they first come empty and do nothing. It's mainly useful to show/hide loading screens, update statuses, put an overlay over the page, or interact with other libraries. Not to confuse with the document event bubble of these events. Please notice that when setting views, phery remote elements inside a view that doesn't do navigate_to calls, will have side effects for events that propagated from the children elements, so when you set an event, like beforeSend on your view if you execute any other phery event that isn't the selector for your in-view link, the beforeSend of the child element will propagate to the view container, and will trigger it's event.

phery.on(event, cb)

These events are triggered globally, independently if called from an existing DOM element or through phery.remote() The event.target points to the related DOM node (that was clicked, or the form that was submitted), if any. When calling phery.remote, the event.target will be the detached DOM element that were created on-the-fly to make the AJAX call, and isn't appended to the page. You may check if the element is temporary using if (event.$target.phery('data', 'temp')){ /* is temp */ } Also, phery provides a shortcut to the event jQuery element through event.$target, that is the same as doing $(event.target), but it's ready to use.

• before: function (event) Triggered before everything, happens right after phery.remote() call. Issuing an event.stopImmediatePropagation() after returning false inside the before callback, will make it so the always event won't trigger.
• after: function (event) Triggered after all the data was parsed.
• beforeSend: function (event, xhr) Triggered before sending the data through AJAX, Useful to add any CSRF protections here
• done: function (event, data, text, xhr) Triggered just before the answer from the response was received successfully and will start to process the data. Returning false halts the processing, make sure to return true
• always: function (event, xhr) Triggered after the data was processed. and is triggered if there was no error.
• fail: function (event, xhr, status, error) When an error happens when requesting to the provided URL. It won't be triggered if the PHP code fails to execute
• exception: function (event, exception) Will be called if any problem happens while processing data, or executing jquery calls
• json: function (event, obj) Returns the json object sent from PHP
• progress: function (event, progress) File upload progress (not available in <= IE9). Can be accessed through the promise progress(callback) too
• params: function (event, params) Pass extra params to the request. Won't overwrite existing params for security reasons

phery.off(name)

Remove a global event bound

phery.reset_to_defaults()

Reset the configuration to the defaults, see phery.config()

phery.log()

Wrapper for the console.log(), but keeps a local history, if you enable it in phery.config()

phery.view(config)

Config the page to render AJAX partial views

Retrieve the data and functions associated with the container with:

Example:

and the PHP side:

phery.config(key, value)

The current configuration options that are available in phery. Reminding that additional configurations and modifications on the AJAX calls can be done using $.ajaxSetup() The options can be set using the key:value in the key parameter, or using a string and value. Each option can be accessed using dot notation inside the string

phery.lock_config()

Locks the configuration, so that nobody can change the configuration again using phery.config() Works as an extra safety measure against people messing with your project settings

Misc options

• cursor (true / false, defaults to true): Change the cursor to wait/busy on any ajax call
• default_href (string / false, defaults to false): Set a common url to all calls, being able to override this to any href property attached to the element
• ajax.retries (int, defaults to 0): Number of retries on error before returning the error callback
• enable.log (true / false, defaults to false): Enable displaying of exceptions or errors, for debugging purposes
• enable.autolock (true / false, defaults to false): Locks the config for the instance after the window has completly loaded, making it impossible to make changes to it, as an extra safety measure against tampering, and works the same way as calling phery.lock_config() but on $(window).on('load').
• enable.log_history (true / false, defaults to false): Keep the log of errors that can be accessed through phery.log()
• enable.only (true / false, defaults to false): Make all AJAX calls, per element, be called one at a time. Multiple clicks or form submissions won't make new AJAX until the last one is done. This option can be set using $(el).phery('data', 'only', true); or creating the element using ` ordata-phery-only="1"`
• enable.php_string_callbacks (true / false, defaults to false): jQuery functions like animate or each that take callbacks, can have the callback defined as a string inside PHP if this is enabled. You may also create a function that will have the current calling element as context (the this keyword)
• enable.per_element.events (true / false, defaults to true): Enable phery:* events on each element
• enable.clickable_structure (true / false, defaults to false): Enable clicking on HTML structural elements, like DIV, HTML, etc. They are disabled by default, but can be enabled manually and locally per element using data-phery-clickable="1" to the tag, or using $('div').phery('data', 'clickable', 1)

Inline

• inline.enable (true / false, defaults to false): Enables phery.js to load responses inline, using phery.load('<?=PheryResponse::factory()->render(); ?>'); or ready-to-use string ` will generate thephery.load` string automatically.
• inline.once (true / false, defaults to false): Make it so it can only be loaded once on page load, and won't be able to call it again later, for security reasons.

Debugging

• debug.enable (true / false, defaults to false): enable verbose to keep track of each step defined below. Don't enable it in production since it's really verbosely
• debug.display.events (true / false, defaults to true): display events debug
• debug.display.remote (true / false, defaults to true): display remote calls
• debug.display.config (true / false, defaults to true): display config changes

Delegation

If you specify a string, it will be appended phery.config('delegate.confirm', 'focusin') becomes ['click','focusin'], passing a array, it wil be rewritten phery.config('delegate.confirm', ['focusin']) becomes ['focusin']

• delegate.confirm (selector => [data-phery-confirm]:not(form)) (string, defaults to ['click']): Confirm alert
• delegate.form (selector => form[data-pheryremote]) (string, defaults to ['submit']): Form submission
• delegate.select_multiple (selector => select[data-phery-remote][multiple]) (string, defaults to ['blur']): Event on select multiple element
• delegate.select (selector => select[data-phery-remote]:not([multiple])) (string, defaults to ['change']): Event on select element
• delegate.tags (selector => [data-remote]:not(form,select)) (string, defaults to ['click']): Clicks on elements, like A

Per element events

Per element events are the same from global events. Refer to phery.on above for description for each event. They can be disabled using phery.config('enable.per_element.events', false); since they are enabled by default These events will bubble to the document DOM, so you may catch them using, for example:

• phery:before: function (event)
• phery:beforeSend: function (event, xhr)
• phery:done: function (event, data, text, xhr)
• phery:always: function (event, xhr)
• phery:fail: function (event, xhr, status, error)
• phery:after: function (event)
• phery:exception: function (event, exception)
• phery:json: function (event, obj)
• phery:params: function (event, obj)

License

Released under the MIT license