Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/darkghosthunter/preloader
Preloader helper to create a PHP-ready preload script from Opcache.
https://github.com/darkghosthunter/preloader
Last synced: about 8 hours ago
JSON representation
Preloader helper to create a PHP-ready preload script from Opcache.
- Host: GitHub
- URL: https://github.com/darkghosthunter/preloader
- Owner: DarkGhostHunter
- License: mit
- Created: 2019-12-01T18:55:45.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-18T09:18:38.000Z (4 months ago)
- Last Synced: 2024-09-19T07:12:42.368Z (14 days ago)
- Language: PHP
- Size: 99.6 KB
- Stars: 430
- Watchers: 15
- Forks: 25
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://packagist.org/packages/darkghosthunter/preloader) [](https://packagist.org/packages/darkghosthunter/preloader)
[](https://coveralls.io/github/DarkGhostHunter/Preloader?branch=master)
# Opcache Preloader
Get the best options to keep your application fast as ever, with just one line.
This package generates a [PHP preloading](https://www.php.net/manual/en/opcache.configuration.php#ini.opcache.preload) script from your Opcache statistics automatically. No need to hack your way in.
> If you're looking for preloading your Laravel project, check [Laragear Preload](https://github.com/Laragear/Preload).
## Table of Contents
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [How it works](#how-it-works)
- [Configuration](#configuration)
* [Conditions](#conditions)
+ [`when()`](#when)
+ [`whenOneIn()`](#whenOneIn)
* [Listing](#listing)
+ [`append()`](#append)
+ [`exclude()`](#exclude)
+ [`selfExclude()`](#selfexclude)
* [Generation](#generation)
+ [`memoryLimit()`](#memorylimit)
+ [`useRequire()`](#userequire)
+ [`ignoreNotFound()`](#ignorenotfound)
* [Compilation](#compilation)
+ [`writeTo()`](#writeto)
+ [`getList()`](#getlist)
- [Safe Preloader](#safe-preloader)
- [Example](#example)
- [Security](#security)
- [License](#license)
## Requirements
* PHP 7.4.3, PHP 8.0 or later.
* [Opcache & Preloading enabled](https://www.php.net/manual/en/book.opcache.php) (`ext-opcache`).
* Composer Autoloader (optional).
## Installation
Require this using Composer into your project
composer require darkghosthunter/preloader
> This package doesn't require `ext-opcache` to install. Just be sure to have it [enabled in your application server](https://www.php.net/manual/en/book.opcache.php).
## Usage
Anywhere in your application, where Opcache is **enabled** and running, call `Preloader` with where to output the compiled script:
```php
writeTo(__DIR__.'/preloader.php');
```
This will automatically gather Opcache statistics, and write an optimized `preload.php` file. In this case, the file will be created in the same directory the Preloader was called.
www
└── app
├── PreloaderCall.php
└── preload.php
Once generated, tell PHP to use this file as a preloader at start up in your `php.ini`.
```ini
opcache.preload=/www/app/preload.php
```
Once the script is generated, **you're encouraged to restart your PHP process** (or server, in some cases) to pick up the generated preload script. Only generating the script [is not enough](https://www.php.net/manual/en/opcache.preloading.php).
> If you use Preloader when Opcache is disabled or without hits, you will get an Exception.
## How it works
This package asks Opcache only for the most requested files and compiles a list from it. You can [check this article in Medium about that preload](https://medium.com/p/9ede756f292c/).
Since the best statistics are those you get **after** your application has been running for a while, you can use your own mechanisms to compile the list only after certain conditions are met.
Don't worry, you can configure what and how compile the list.
## Configuration
You can configure the Preloader to run when a condition is met, limit the file list, among what other things.
### Conditions
#### `when()`
This method executes the given callable and checks if the preloader should compile the list or not based on what the callable returning value evaluates.
```php
when(fn () => $app->cache()->get('should_run'));
```
This is handy if you can combine the condition with your own application logic, like a given number of requests, or an external signal.
#### `whenOneIn()`
This is method is just a helper to allows you to quickly generate a Preloader script in one of a given number of random chances.
```php
whenOneIn(50);
```
For example, the above makes the Preloader generate a compiled list one in fifty chances.
### Listing
#### `append()`
You can add a list of directories to the compiled list. The files inside them will be appended to the compiled list, and won't account for memory restrictions.
```php
append([
__DIR__ . '/files/*/more_files',
__DIR__ . '/classes/'
]);
```
> If the files you're adding are already in the compiled list, these will be removed from the included files to avoid effective duplicates.
This packages includes [Symfony Finder](https://symfony.com/doc/current/components/finder.html), so as an alternative you can pass a closure that receives the Finder instance along with the files you want to append.
```php
append(function (Finder $find) {
$find->files()->in('/package')->name(['*.php', '*.twig']);
});
```
> The `exclude()` method take precedence over `append()`. If you exclude a file that is later appended, you won't exclude it at all.
#### `exclude()`
This method excludes files from inside directories from Opcache list, which later end up in the Preload list. Excluding files may free up the memory of the compiled list, leaving space for others to be included.
You can pass an array of paths, which is good if you already have a list ready to exclude.
```php
exclude([
__DIR__ . '/files/*/more_files',
__DIR__ . '/vendor'
]);
```
This packages includes [Symfony Finder](https://symfony.com/doc/current/components/finder.html), so as an alternative you can pass a Closure receiving the Finder instance along with the files you want to exclude.
```php
exclude(function (Finder $find) {
$find->files()->in('/package')->name(['*.php', '*.twig']);
});
```
> The `exclude()` method take precedence over `append()`. If you exclude a file that is later appended, you won't exclude it at all.
#### `selfExclude()`
Automatically excludes the Package files from the Preload list.
By default, the package is not excluded, since it may be part of the most requested files. It's recommended to exclude the package only if you have total confidence it won't be called once Opcache Preloading is enabled.
```php
selfExclude();
```
### Generation
#### `memoryLimit()`
By default, Preloader defaults a memory limit of 32MB, which is enough for *most* applications. The Preloader will generate a list of files until that memory limit is reached.
You can set your own memory limit in **MB**.
```php
memoryLimit(32);
```
This takes into account the `memory_consumption` key of each script cached in Opcache, not the real file size.
> This limit doesn't have any relation with Opcache memory limit.
To disable the limit, use `memoryLimit(0)`. This will list **ALL** available files from Opcache.
#### `useRequire()`
By default, the Preloader will upload the files to Opcache using `opcache_compile_file()`. This avoids executing any file in your project, but no links (traits, interfaces, extended classes, ...) will be resolved from the files compiled. You may have some warnings of unresolved links when preloading (nothing too dangerous).
You can change this using `useRequire()`, which changes to `require_once`, along the path the Composer Autoloader (usually at `vendor/autoload.php`) to resolve the links.
```php
useRequire(__DIR__ . '/../vendor/autoload.php');
```
> You may get some warnings when compiling a file with unresolved links. These are not critical, since these files usually are the least requested in your application.
#### `ignoreNotFound()`
Some applications may create files at runtime that are genuinely cached by Opcache, but doesn't exist when the application is firstly deployed.
To avoid this problem, you can use the `ignoreNotFound()`, which will compile a script that ignore files not found or are unreadable.
```php
ignoreNotFound();
```
> If the file is readable but its preloading returns an error, it will throw an exception nonetheless.
### Compilation
#### `writeTo()`
This will automatically create a PHP-ready script to preload your application. It will return `true` on success, and `false` when the when the conditions are not met.
```php
writeTo(__DIR__ . '/preloader.php');
```
You can issue `false` as second parameter to not overwrite any existing file in the write path. If a file is found, no preload logic will be run.
#### `getList()`
You can retrieve the raw list of files that should be included as an array using `getList()`.
```php
getList();
```
This may become handy if you have your own script, or you just want to tinker around it.
## Safe Preloader
This packages comes with a handy Safe Preloader, located in `helpers/safe_preloader.php`.
What it does is very simple: it registers a shutdown function for PHP that is executed after the preload script finishes, and registers any error the script may have returned so you can debug it.
To use it, copy the file into an accessible path for PHP, and along with the real preloader script, reference it in your `php.ini`:
```ini
opcache.preload=/www/app/safe_preloader.php
```
```php
run();
$response->sendToBrowser();
Preloader::make()
->whenOneIn(100)
->memoryLimit(64)
->writeTo(PHP_LOCALSTATEDIR . '/preload.php'); // put it in /var.;
```
## Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.