Deployment

Introduction

When you’re ready to deploy your Maravelith application to production, there are some important things you can do to make sure your application is running as efficiently as possible. In this document, we’ll cover some great starting points for making sure your Maravelith application is deployed properly.

Server Requirements

The Maravelith framework has a few system requirements. You should ensure that your web server has the following minimum PHP version and extensions:

  • PHP >= 8.1
  • Ctype PHP Extension
  • cURL PHP Extension
  • DOM PHP Extension
  • Fileinfo PHP Extension
  • Filter PHP Extension
  • Hash PHP Extension
  • Mbstring PHP Extension
  • OpenSSL PHP Extension
  • PCRE PHP Extension
  • PDO PHP Extension
  • Session PHP Extension
  • Tokenizer PHP Extension
  • XML PHP Extension

Server Configuration

Nginx

If you are deploying your application to a server that is running Nginx, you may use the following configuration file as a starting point for configuring your web server. Most likely, this file will need to be customized depending on your server’s configuration. If you would like assistance in managing your server, consider using a first-party Maravelith server management and deployment service such as Laravel Forge.

Please ensure, like the configuration below, your web server directs all requests to your application’s public/index.php file. You should never attempt to move the index.php file to your project’s root, as serving the application from the project root will expose many sensitive configuration files to the public Internet:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Optimization

Autoloader Optimization

When deploying to production, make sure that you are optimizing Composer’s class autoloader map so Composer can quickly find the proper file to load for a given class:

composer install --optimize-autoloader --no-dev

[!NOTE]
In addition to optimizing the autoloader, you should always be sure to include a composer.lock file in your project’s source control repository. Your project’s dependencies can be installed much faster when a composer.lock file is present.

By using the --classmap-authoritative flag, Composer:

  • disables filesystem scanning for classes not found in the classmap (including class aliases not explicitly in the map).
  • improves performance because class_exists() calls return immediately — no fallback to PSR-4/PSR-0 filesystem checks.
  • assumes the classmap is complete: if a class isn’t in the map, it doesn’t exist.

[!NOTE] Class aliases created with class_alias() are not included in the classmap automatically, so those classes may fail to autoload.

When using --no-scripts flag, be sure to call:

composer dump-autoload

or explicitly call all the cache commands from the composer.json->scripts->post-autoload-dump of the template you are using (Maravel or Maravelith). This will improve the boot time of the application. See more below.

Caching Configuration

When deploying your application to production, you should make sure that you run the config:cache Artisan command during your deployment process:

php artisan config:cache

This command will combine all of Maravelith’s configuration files into a single, cached file, which greatly reduces the number of trips the framework must make to the filesystem when loading your configuration values.

[!WARNING]
If you execute the config:cache command during your deployment process, you should be sure that you are only calling the env function from within your configuration files. Once the configuration has been cached, the .env file will not be loaded and all calls to the env function for .env variables will return null.

Caching Events

If your application is utilizing event discovery, you should cache your application’s event to listener mappings during your deployment process. This can be accomplished by invoking the event:cache Artisan command during deployment:

php artisan event:cache

[!NOTE] It can also include the observers.

Caching Routes

If you are building a large application with many routes, you should make sure that you are running the route:cache Artisan command during your deployment process:

php artisan route:cache

This command reduces all of your route registrations into a single method call within a cached file, improving the performance of route registration when registering hundreds of routes.

Caching Views

When deploying your application to production, you should make sure that you run the view:cache Artisan command during your deployment process:

php artisan view:cache

This command precompiles all your Blade views so they are not compiled on demand, improving the performance of each request that returns a view.

Caching Autowiring

When deploying your application to production, you should make sure that you run the autowiring:cache Artisan command during your deployment process:

php artisan autowiring:cache

This avoids runtime reflection on method and construct autowire, improving the performance. To configure what classes should be cached, add in app.autowiring config the list: These are the defaults:

    /**
     * artisan autowiring:cache source paths for public methods (except __construct which is implicitly handled)
     * The CallQueuedHandler, controllers, middlewares, bult-in commands, service providers
     *  + other classes resolved from Container during the autowiring:cache command execution are handled automatically
     * 'path' can be a single class or a directory
     */
    'autowiring' => [
        [
            'path' => \app()->path() . DIRECTORY_SEPARATOR . 'Console' . DIRECTORY_SEPARATOR . 'Commands',
            'methods' => ['handle', '__invoke'],
        ],
        [
            'path' => \app()->path() . DIRECTORY_SEPARATOR . 'Jobs',
            'methods' => ['handle', '__invoke'],
        ],
        [
            'path' => \app()->path() . DIRECTORY_SEPARATOR . 'Http' . DIRECTORY_SEPARATOR . 'Requests',
            'methods' => ['validator', 'authorize', 'after', 'rules'],
        ],
    ],

Check bootstrap/cache/autowiring.php.

[!NOTE] If the concrete has contextual bindings (and constructor parameters) the old reflection is still used.

If the parameters are sent as array list, concrete will be instantiated directly with them. On failure, it will default to the old reflection but at the cost of building an Exception.

If the first parameters are sent as list and the last one(s) need to be auto-resolved, the above exception scenario will happen, which is slow. Always send all parameters as list, in the right order.

The method autowiring (so non __construct) does not support parameters as list!

Caching Commands

When deploying your application to production, you should make sure that you run the commands:cache Artisan command during your deployment process:

php artisan commands:cache

This avoids runtime reflection and instantiation on all commands, improving the performance.

Debug Mode

The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your application’s .env file.

[!WARNING]
In your production environment, this value should always be false. If the APP_DEBUG variable is set to true in production, you risk exposing sensitive configuration values to your application’s end users.

Easy Deployment With Forge / Vapor

Laravel Forge

If you aren’t quite ready to manage your own server configuration or aren’t comfortable configuring all the various services needed to run a robust Maravelith application, Laravel Forge is a wonderful alternative.

Laravel Forge can create servers on various infrastructure providers such as DigitalOcean, Linode, AWS, and more. In addition, Forge installs and manages all the tools needed to build robust Maravelith applications, such as Nginx, MySQL, Redis, Memcached, Beanstalk, and more.

[!NOTE]
Want a full guide to deploying with Laravel Forge? Check out the Laravel Bootcamp and the Forge video series available on Laracasts.

Laravel Vapor

If you would like a totally serverless, auto-scaling deployment platform tuned for Maravelith, check out Laravel Vapor. Laravel Vapor is a serverless deployment platform for Maravelith, powered by AWS. Launch your Maravelith infrastructure on Vapor and fall in love with the scalable simplicity of serverless. Laravel Vapor is fine-tuned by Maravelith’s creators to work seamlessly with the framework so you can keep writing your Maravelith applications exactly like you’re used to.

This site uses Just the Docs, a documentation theme for Jekyll.