Jaxon v4 is coming

[feuzeu]

Hi All,

I've started working on the v4 releases of the Jaxon library, and this is an overview of the current and upcoming changes.

Any comment, suggestion or question is welcome.

New features

Many parts of the library have been rewritten, many classes have been moved and renamed, for more simplicity, readability and performance.

• The DI container has been greatly improved, and is now widely used across the library. For example, there's no more calls to the global jaxon() function in the library.
• Interfaces have been defined for request and response plugins, making it easier to understand their features.
• New exception classes are added.
• The event dispatcher is removed.
• Some utility features (translator, templates, config, etc) are moved to the new jaxon-utils package.
• There are improvements on the request and response plugin system, the request factory, the upload handler, and the code generator.

The next (and last?) upcoming feature is annotation. It will allow the developer to define properties of the exported classes together with the classes, using the PHP annotation syntax.

For example, with the following code, Jaxon will upload the files in the HTML input component with id html_field_id.

    /**
     * Save the uploaded files
     * 
     * @upload(field="html_field_id")
     *
     * @return Response
     */
    public function saveFiles()
    {
        $files = jaxon()->upload()->files();
        // Process the uploaded files.
    }

Annotations will be defined for all the options of class registration, and maybe also for validation.

Breaking changes

For now, these are the three breaking changes, and I think they will be no new one.

1. The Response object.

Instantiating the Response class will not work anymore, since its constructor now takes parameters. The Jaxon class must be used to create response objects. Before

$response = new Response();

After

$response = jaxon()->newResponse();

It is still recommended to use the global response object.

$response = jaxon()->getResponse();

2. The plugin registration.

The request and response plugins must now be registered by class name, and not by instance. Before

jaxon()->registerPlugin(new Plugin());

After

// The second parameter must be the same value as returned by the getName() method of the plugin class.
jaxon()->registerPlugin(Plugin::class, 'name');

By default, the plugin instance will be created using the auto() method of the Jaxon DI, allowing the constructor to take any object registered in the DI as parameter. Optionally, the DI can be explicitely set for the plugin class, before the registration.

jaxon()->di()->set(Plugin::class, function($c) {
    // Create and return an instance of the Plugin class.
});
jaxon()->registerPlugin(Plugin::class, 'name');

Additionally, the canProcessRequest() method of the request plugin interface is now static, so it can be called without creating an instance of the class. Only the request plugin that will actually process the current request will be instantiated.

3. The integration plugins

The interface for integration plugin is now simpler. The processRequest() method is removed from the Jaxon\App\AppTrait trait, and many other methods are added to define views, session manager, logger and container, makig it easier to define new plugins.

[feuzeu]

Hi all,

One feature that has just been added to this library, and which unfortunately I did not list in the above message, is the PSR7 and PSR15 support. Jaxon is now able to handle input HTTP requests and return HTTP responses as defined by the PSR7 message interfaces. It also provides PSR15 middlewares and request handlers, making it easy to integrate with PHP frameworks or CMSs that support these standards.

For example, with the Slim framework v4, this is how easy it will be to integrate with Jaxon.

<?php

use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
use Slim\Factory\AppFactory;
use Slim\Psr7\Response;

require __DIR__ . '/../vendor/autoload.php';

$app = AppFactory::create();

// Jaxon middleware to load config
$jaxonConfigMiddleware = function (Request $request, RequestHandler $handler) {
    return jaxon()->psr()->config("/path/to/jaxon/config/file.php")->process($request, $handler);
};
// Jaxon middleware to process ajax requests
$jaxonAjaxMiddleware = function ($request, $handler) {
    return jaxon()->psr()->ajax()->process($request, $handler);
};

// Process Jaxon ajax request
$app->get('/jaxon', function () {
    // Could not process the request. Show an error.
})->add($jaxonConfigMiddleware)->add($jaxonAjaxMiddleware);

// Insert Jaxon codes in a page
$app->get('/', function () {
    // Display a page with Jaxon js and css codes.
})->add($jaxonConfigMiddleware);

[feuzeu]

Hi,

I just merged the annotations on the main branch. These are a few examples of how they are used. Most of them may also be defined as class level.

File upload.

    /**
     * @upload('field' => 'html_field_id')
     * @return Response
     */
    public function saveFiles()
    {
        $files = jaxon()->upload()->files();
        // Process the uploaded files.
        return $this->response;
    }

Do not export a method to js.

    /**
     * @exclude
     * @return Response
     */
    public function noJs()
    {
        return $this->response;
    }

Callbacks.

    /**
     * @before('call' => 'preProcess')
     * @after('call' => 'postProcess', 'with' => ['param1', 'param2'])
     * @return Response
     */
    public function withCallbacks()
    {
        return $this->response;
    }

[feuzeu]

Hi,

I've published demo packages for framework integration with Jaxon, which are easier to install and run than the previous ones.

• Symfony: https://github.com/jaxon-php/jaxon-demo-symfony
• Laravel: https://github.com/jaxon-php/jaxon-demo-laravel
• CakePHP: https://github.com/jaxon-php/jaxon-demo-cakephp
• Slim: https://github.com/jaxon-php/jaxon-demo-slim
• Yii: https://github.com/jaxon-php/jaxon-demo-yii
• CodeIgniter: https://github.com/jaxon-php/jaxon-demo-codeigniter

[feuzeu]

Hi,

I decided to add a new feature that was not initially planned on this new release.

The upload feature is moved to a separate package https://github.com/jaxon-php/jaxon-upload, and will now use the PHP League Flysytem package https://flysystem.thephpleague.com/docs/ to store uploaded files.

It will allow to store the uploaded files to various storage systems, in addition to the local disk.

Following this change, the upload feature will be disabled by default on the core package.