helthe / turbolinks
Helthe Turbolinks Component
Installs: 116 583
Dependents: 4
Suggesters: 0
Security: 0
Stars: 111
Watchers: 8
Forks: 10
Open Issues: 1
Requires
- php: ^7.1||^8.0
- symfony/http-foundation: ^4.3.4||^5.0
Requires (Dev)
- phpunit/phpunit: ^7.5.15||^8.4||^9.3.3
- symfony/http-kernel: ^4.3.4||^5.0
Suggests
- symfony/http-kernel: Required for usage with the Symfony HttpKernel Component
README
Helthe Turbolinks is a direct port of the rails turbolinks gem for projects using the Symfony HttpFoundation Component.
Versions
Current versions of the following gems are used:
- turbolinks: v5.0.0
Performance
Turbolinks makes following links in your web application faster. Instead of letting the browser recompile the JavaScript and CSS between each page change, it keeps the current page instance alive and replaces only the body and the title in the head.
Performance improvements will vary depending on the amount of CSS and Javascript you are using. You can get up to a 2X increase when using a lot of Javascript and CSS. You can find the rails benchmarks here.
Installation
Using Composer
Manually
Add the following in your composer.json:
{
"require": {
// ...
"helthe/turbolinks": "~4.0"
}
}
Using the command line
$ composer require 'helthe/turbolinks=~4.0'
Usage
Using turbolinks requires both the usage of the javascript library and modifying the PHP response so that it can be properly processed by turbolinks.
PHP
There are multiple ways to decorate the PHP response for turbolinks.
Manually
You can manually decorate the response with the Turbolinksobject.
<?php use Helthe\Component\Turbolinks\Turbolinks; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; // ... $turbolinks = new Turbolinks(); $turbolinks->decorateResponse($request, $response);
Event Listeners
You can add an event listener to the dispatcher that is passed to the HttpKernel.
<?php use Helthe\Component\Turbolinks\EventListener\TurbolinksListener; use Helthe\Component\Turbolinks\Turbolinks; // ... // Symfony\Component\EventDispatcher\EventDispatcherInterface $dispatcher->addSubscriber(new TurbolinksListener(new Turbolinks()));
Stack Middleware
You can decorate the response using the supplied Stack middleware.
<?php use Helthe\Component\Turbolinks\StackTurbolinks; use Helthe\Component\Turbolinks\Turbolinks; // ... $app = new StackTurbolinks($app, new Turbolinks());
Javascripts
Both the original coffeescript version and compiled version of each script are available for use.
Using turbolinks.js
To enable turbolinks, all you need to do is add the compiled turbolinks javascript to your layout in the <head>section.
Integrating turbolinks with another PHP project
The goal of the component is to offer a base package for integration with other PHP projects using the Symfony HttpFoundation or HttpKernel components.
You can do so by either using the supplied middleware that follows the Stack convention or by adding the supplied event listenter to the HttpKernel event dispatcher.
Instead of copying over the compiled javascripts to your projects, try to use your project tools to copy them over. You should always be able to fallback on the composer script hooks like post-install-cmd and post-update-cmd.
List of integrations
- HeltheTurbolinksBundle (Symfony 2)
- Frenzy Turbolinks Package (Laravel)
- Silex Turbolinks (Silex)
Compatibility
The turbolinks javascript is designed to work with any browser that fully supports pushState and all the related APIs. This includes Safari 6.0+ (but not Safari 5.1.x!), IE10, and latest Chromes and Firefoxes.
Do note that existing JavaScript libraries may not all be compatible with Turbolinks out of the box due to the change in instantiation cycle. You might very well have to modify them to work with Turbolinks' new set of events. For help with this, check out the Turbolinks Compatibility project.
Additional Resources
Please refer to the turbolinks project if you require additional information on the javascript libraries and their usage.
Bugs
For bugs or feature requests, please create an issue.