Extremely Easy Ext.Direct integration with PHP

[j.bruni]

*** Compatible with ExtJS 4 ***

This is an updated / refactored version of "Easy Ext.Direct integration with PHP"

How to use:

1) PHP

<?php

require 'ExtDirect.php';

class Server
{
    public function date( $format )
    {
        return date( $format );
    }
}

ExtDirect::provide( 'Server' );

?>

Here, "Server" is the PHP class that we want to provide access from the JavaScript code. It could be any other class.

2) HTML:

<script type="text/javascript" src="ext-direct.php?javascript"></script>

Here, "ext-direct.php" points to the PHP file shown on item 1. The "?javascript" query string is necessary, because the default output is on JSON format (good for Ext Designer).

3) JavaScript:

Ext.php.Server.date( 'Y-m-d', function(result){ alert( 'Server date is ' + result ); } );

Here, to call the "date" method from PHP "Server" class, we prepended the default namespace Ext.php. The first parameter is the $format parameter. The second parameter is the JavaScript callback function that will be executed after the AJAX call has been completed. Here, an alert box shows the result.



What are you waiting for the download?

It includes:

ExtDirect.php - This is the file you include in your PHP script.
example.php - This is a working sample (PHP part).
example.html - The HTML and JavaScript parts of the working sample.

In the next post, I tell you about the features and configuration options.

Thanks.

---

The current latest version is ExtDirect_2011-11-08.zip, which you can download below:

[khebs@live.com]

You are brilliant!

[j.bruni]

Thanks, Khebs!

You haven't seen nothing yet!

Look at the Features

- API declaration with several classes (not limited to a single class)

- API "url", "namespace" and "descriptor" settings ("ExtDirect" class assigns them automatically if you don't)

- Two types of API output format: "json" (for use with Ext Designer) and "javascript" (default: json)

- You choose if the "len" attribute of the actions will count only the required parameters of the PHP method, or all of them (default: all)

- You choose whether inherited methods will be declared in the API or not (default: no)

- You choose whether static methods will be declared in the API or not (default: no)

- Instantiate an object if the called method is static? You choose! (default: no)

- Call the class constructor with the actions parameters? You choose! (default: no)

- "debug" option to enable server exceptions to be sent in the output of API action results (default: off)

- "utf8_encode" option to automatically apply UTF8 encoding in API action results (default: off)

Learn how to use all these configuration options in the next post. It is so simple!

[j.bruni]

Hey! Forgot to mention in the features list:

- Handles forms

- Handles file uploads

[j.bruni]

Easy.

If the configuration option name is "configuration_name" and the configuration value is $value, use this syntax:

ExtDirect::$configuration_name = $value; 

And that's all.

Now, let's see the available configuration options:

- name: api_classes
- type: array of strings
- meaning: Name of the classes to be published to the Ext.Direct API
- default: empty
- comments: This option is overriden if you provide a non-empty $api_classes parameter for the "ExtDirect::provide" method. Choose one or another. If you want to declare a single class, you can set $api_classes as a string, instead of an array.
- example

ExtDirect::$api_classes = array( 'Server', 'OtherClass',  'StoreProvider' ); 

- name: url
- type: string
- meaning: Ext.Direct API attribute "url"
- default: $_SERVER['PHP_SELF']
- comments: Sometimes, PHP_SELF is not what we want. So, it is possible to specify the API URL manually.
- example

ExtDirect::$url = '/path/to/my_php_script.php'; 

- name: namespace
- type: string
- meaning: Ext.Direct API attribute "namespace"
- default: "Ext.php"
- comments: Feel free to choose your own namespace, according to ExtJS rules for it.
- example

ExtDirect::$namespace = 'Ext.Dharma'; 

- name: descriptor
- type: string
- meaning: Ext.Direct API attribute "descriptor"
- default: "Ext.php.REMOTING_API"
- comments: Feel free to choose your own descriptor, according to ExtJS rules for it, and to the chosen namespace.
- example

ExtDirect::$descriptor = 'Ext.Dharma.REMOTING_API'; 

- name: count_only_required_params
- type: boolean
- meaning: Set this to true to count only the required parameters of a method for the API "len" attribute
- default: false
- example

ExtDirect::$count_only_required_params = true; 

- name: include_static_methods
- type: boolean
- meaning: Set this to true to include static methods in the API declaration
- default: false
- example

ExtDirect::$include_static_methods = true; 

- name: include_inherited_methods
- type: boolean
- meaning: Set this to true to include inherited methods in the API declaration
- default: false
- example

ExtDirect::$include_inherited_methods = true; 

- name: instantiate_static
- type: boolean
- meaning: Set this to true to create an object instance of a class even if the method being called is static
- default: false
- example

ExtDirect::$instantiate_static = true; 

- name: constructor_send_params
- type: boolean
- meaning: Set this to true to call the action class constructor sending the action parameters to it
- default: false
- example

ExtDirect::$constructor_send_params = true; 

- name: debug
- type: boolean
- meaning: Set this to true to allow exception detailed information in the output
- default: false
- example

ExtDirect::$debug = true; 

- name: utf8_encode
- type: boolean
- meaning: Set this to true to pass all action method call results through utf8_encode function
- default: false
- example

ExtDirect::$utf8_encode = true; 

- name: default_api_output
- type: string
- meaning: API output format - available options are "json" (good for Ext Designer) and "javascript"
- default: "json"
- comments: Another way to enforce "javascript" output is to append the "?javascript" query string in the end of your PHP script URL; do this in the HTML <script> tag that refers to your API
example

ExtDirect::$default_api_output = "javascript"; 

[khebs@live.com]

Yes i was playing with it, very good indeed.. and nice one w/ json & javascript nothing is much simpler than this.. thanks for sharing!

[Andrew Peacock]

Thanks J. Saw your response in your other post, skipped over here, and like what I see. Thanks for sharing with everyone. Andy

[cbj4074]

What do I need to set count_only_required_params to, so that optional parameters are optional?

I am wondering the same thing, and if the response that follows is still relevant.

...
Finally, @AndreKR...

This post (http://www.sencha.com/forum/showthre...l=1#post480214) teaches how apply configurations (I know you read it, I am linking for the others...)

All configurations must come before the "ExtDirect::provide" call:

ExtDirect::$configuration_name = $value; 

In your case, you want to perform the following configuration:

ExtDirect::$count_only_required_params = true; 

This will make the "len" property of the respective API declaration correspond to the number of required parameters. So, for a PHP method declared like this...

function calculate_something( $needed, $optional = 9 ) 

...the "len" value will be "1", instead of "2".

And this is all.

Now, ExtJS requires you to make the remote function call with the number of parameters declared in the "len" property. In other words: there is no such things as "optional parameters" in the client-side, because of the way ExtJS Direct is designed.

In the example, you need to choose: it will be either "1" or "2" parameters. You simply can't choose "1" and optionally "2", at the ExtJS side. Makes sense?

I am using the sample descriptor code (for PHP) that is provided with the Ext Direct Pack and the mechanism for setting default configuration values seems to have changed:

$api = new ExtDirect_API();

$api->setRouterUrl('router.php'); // default
$api->setCacheProvider($cache);
$api->setNamespace('Ext.ss');
$api->setDescriptor('Ext.ss.APIDesc');
$api->setDefaults(array(
    'autoInclude' => true,
    'basePath' => 'classes'
)); 

Regarding ExtJS Direct configuration, in general, I am wondering if these configuration directives are still relevant:

Easy.

If the configuration option name is "configuration_name" and the configuration value is $value, use this syntax:

ExtDirect::$configuration_name = $value; 

And that's all.

Now, let's see the available configuration options:

- name: api_classes
- type: array of strings
- meaning: Name of the classes to be published to the Ext.Direct API
- default: empty
- comments: This option is overriden if you provide a non-empty $api_classes parameter for the "ExtDirect::provide" method. Choose one or another. If you want to declare a single class, you can set $api_classes as a string, instead of an array.
- example

ExtDirect::$api_classes = array( 'Server', 'OtherClass',  'StoreProvider' ); 

- name: url
- type: string
- meaning: Ext.Direct API attribute "url"
- default: $_SERVER['PHP_SELF']
- comments: Sometimes, PHP_SELF is not what we want. So, it is possible to specify the API URL manually.
- example

ExtDirect::$url = '/path/to/my_php_script.php'; 

- name: namespace
- type: string
- meaning: Ext.Direct API attribute "namespace"
- default: "Ext.php"
- comments: Feel free to choose your own namespace, according to ExtJS rules for it.
- example

ExtDirect::$namespace = 'Ext.Dharma'; 

- name: descriptor
- type: string
- meaning: Ext.Direct API attribute "descriptor"
- default: "Ext.php.REMOTING_API"
- comments: Feel free to choose your own descriptor, according to ExtJS rules for it, and to the chosen namespace.
- example

ExtDirect::$descriptor = 'Ext.Dharma.REMOTING_API'; 

- name: count_only_required_params
- type: boolean
- meaning: Set this to true to count only the required parameters of a method for the API "len" attribute
- default: false
- example

ExtDirect::$count_only_required_params = true; 

- name: include_static_methods
- type: boolean
- meaning: Set this to true to include static methods in the API declaration
- default: false
- example

ExtDirect::$include_static_methods = true; 

- name: include_inherited_methods
- type: boolean
- meaning: Set this to true to include inherited methods in the API declaration
- default: false
- example

ExtDirect::$include_inherited_methods = true; 

- name: instantiate_static
- type: boolean
- meaning: Set this to true to create an object instance of a class even if the method being called is static
- default: false
- example

ExtDirect::$instantiate_static = true; 

- name: constructor_send_params
- type: boolean
- meaning: Set this to true to call the action class constructor sending the action parameters to it
- default: false
- example

ExtDirect::$constructor_send_params = true; 

- name: debug
- type: boolean
- meaning: Set this to true to allow exception detailed information in the output
- default: false
- example

ExtDirect::$debug = true; 

- name: utf8_encode
- type: boolean
- meaning: Set this to true to pass all action method call results through utf8_encode function
- default: false
- example

ExtDirect::$utf8_encode = true; 

- name: default_api_output
- type: string
- meaning: API output format - available options are "json" (good for Ext Designer) and "javascript"
- default: "json"
- comments: Another way to enforce "javascript" output is to append the "?javascript" query string in the end of your PHP script URL; do this in the HTML <script> tag that refers to your API
example

ExtDirect::$default_api_output = "javascript"; 

Does current (ExtJS 4+), formal documentation of these directives exist? If so, might anyone be able to provide a URL? I have looked and came-up empty.

Thanks in advance.

[lsdriscoll]

Hi j.bruni!

First of all, thanks so much for this package! It's saved so much time.

Second, I have been using it with the charts module and have uncovered a potential problem :
The JSON data always returns table data as strings from the proxy, even if it's marked as an integer in the db. Obviously this broke the charts. I have seen many people on forums having the issue that their charts wouldn't work using a direct proxy, so I'm guessing that this might be an Ext problem instead of relating to your code.

Anyway, as a temporary fix I modified lines 621 & 623 so that the json_encode functions included the JSON_NUMERIC_CHECK flag.

Of course, this isn't ideal as it will force ALL number values to be send as integers, when a string may actually be desired.

Was wondering what your thought were on this?

[j.bruni]

Second, I have been using it with the charts module and have uncovered a potential problem :
The JSON data always returns table data as strings from the proxy, even if it's marked as an integer in the db. Obviously this broke the charts. I have seen many people on forums having the issue that their charts wouldn't work using a direct proxy, so I'm guessing that this might be an Ext problem instead of relating to your code.

Hi! Thanks for your feedback! Sorry for the delay on my reply. Anyway, here are my thoughts on this:

In my point of view, the "potential problem" is not exactly an Ext/JSON issue, but a database issue.

Every data returned from SQL queries is always of string type. The only exception is the null value, which returns as null. Everything else is string, it does not matter the type of the data in the database. A date column, or an integer column... the database query results always arrive in the PHP side as strings.

Also, consider that we can satisfy Ext Data Charts needs of integer values, but will not be able to send JavaScript Date objects, for example, using pure JSON, without any extra processing at the client-side...

So, my approach is: in my server-side app code, I use an intermediary "parse" function which transforms each row of the database result into something ready-to-use for the client side. Something like:

function parse_rows($original_result)
{
    $parsed_result = array();
    foreach($original_result as $row)
    {
        $row['quantity'] = intval($row['quantity']);
        $row['price'] = floatval($row['price']);
        $parsed_result[] = $row;
    }
    return $parsed_result;
}

The important thing here is that we need to transform the database-returned string into its proper integer data-type. In fact, I use this "parse" function to apply other kinds of transformations (for example, joining "first_name" with "last_name" to return a "name" column which does not even exist in the database).

I think this is where the solution should be focused... not at client-side or the JSON encoding. This is my opinion.