DEV Community: Jotcomponents

Laravel deployment with Dynamic Application Version Switching

Jotcomponents — Sun, 02 Aug 2026 13:51:16 +0000

Introduction

Most Laravel deployment procedures assume one of two extremes:

full root access on a dedicated server (and run composer install directly on the box)
cPanel-style shared host where you shuffle a public/ folder into public_html and call it directly.

Neither model fits a workspace that hosts multiple in-flight branches of the same Laravel 11/12 application and needs to switch the live code version without restarting Apache or moving gigabytes of vendor/.

This article describes other deployment topology where the application is split into a private core (above the web root) and a web entry point (the only thing the web server can see), connected by a small PHP orchestrator that rewires three symlinks during deployment of new version of the application. The result is a system where switching the running version of the application is a one-line constant change in a single file.

The Separation Model: Private vs Web

Every deployment (target) workspace follows the same layout:

/var/www/<workspace>/
├── private/        ← Application Core (Outside Web Root)
│   ├── app/
│   ├── bootstrap/
│   ├── config/
│   ├── database/
│   ├── public/      ← Laravel's own public/ (used as symlink target)
│   ├── resources/
│   ├── routes/
│   ├── storage/
│   ├── vendor/
│   ├── build/       ← Vite Asset Manifest & Bundles
│   └── ...
├── private2/        ← A second full copy for app version switching
│   (folder structure same as in `private` folder)
│
├── web/             ← Apache DocumentRoot (public_html)
│   ├── index.php    ← Modified entry point (with app version switch)
│   ├── symlinksSetup.php    ← Symlink Orchestrator
│   ├── .htaccess
│   ├── storage → '../upload/'      (symlink, created by orchestrator)
│   ├── build → '../private/build/' (symlink, created by orchestrator)
│   └── ...
└── upload/          ← Shared storage target (used for media assets)

During a development Vite emits its production bundle to public/build/. For deployment is a production bundle moved to private/build/ (next to the source code it belongs to 'private or private2'). The orchestrator mirrors that link into web/build so Blade views can resolve @vite() references normally.

Here is the simplified shorthand text summarizing the deployment transformation process, tailored for experienced web application workers:

Deployment Transformation Overview

To prepare the application for runtime switching, the deployment script constructs the private and web directories through a structured transformation process.

Application Filtering: The script scans the application root and copies only the essential files into the deploy/private directory. It explicitly strips out development tooling and non-essential directories (such as tests, documentation, and node dependencies) using a predefined exclusion list to keep the deployable artifact clean.
Asset Relocation: Hashed frontend bundles produced by Vite are moved from the standard public build directory into deploy/private/build/. This ensures the compiled production assets reside securely alongside the application core.
Environment Injection: Target-specific overrides are layered into the build without polluting the source repository. Custom configuration files—such as the target's .env, .htaccess, and a modified index.php configured for application switching—are directly merged into the respective deploy/private/ and deploy/web/ directories.
Archive Generation: Finally, the script packages the prepared directories into two timestamped archives (private and web) per environment. These archives are then ready to be transferred and extracted on the target staging or production servers.

The Runtime Orchestrator

This is the code that turns a static private//private2/ pair into a switchable runtime. The version that ships as a test fixture in this
repository lives at web/symlinksSetup.php on the host.

Three responsibilities

The function performs three jobs in order:

Validate the request — refuse to do anything if PRIVATE_CHANGE is not set in .env or if the requested switch value isn't recognised.
Map the requested instance (private or private2) to three concrete symlink definitions: web, storage, and build.
Reconcile the filesystem — if any of the three links is missing or points to the wrong target, tear down all six (the three for each instance) and rebuild the three for the active one.

When a switch is actually required, the function unlinks the three candidate links for both instances before creating the three it needs. That ordering matters: because web/build and web/storage are nested paths, any stale link from the inactive instance is removed first so we never create a symlink whose parent has already been claimed by the wrong target.

The Bootstrap Chain in `index.php`

The orchestrator is only useful if it runs before the Laravel kernel touches the filesystem. The entry point is the customised web/index.php:

define('LARAVEL_START', microtime(true));

require __DIR__.'/symlinksSetup.php';
const APP_SWITCH = 'private'; // Change this to 'private' or 'private2' as needed

symlinksSetup(APP_SWITCH);

// Determine if the application is in maintenance mode...
if (file_exists($maintenance = __DIR__.'/../'.APP_SWITCH.'/storage/framework/maintenance.php')) {
    require $maintenance;
}

// Register the Composer autoloader...
require __DIR__.'/../'.APP_SWITCH.'/vendor/autoload.php';

// Bootstrap Laravel and handle the request...
(require_once __DIR__.'/../'.APP_SWITCH.'/bootstrap/app.php')
    ->handleRequest(Request::capture());

All three follow-up paths use APP_SWITCH. The maintenance check, the autoloader, and the bootstrap path all interpolate the constant. That uniformity is what makes the single-line switch effective:
changing APP_SWITCH from 'private' to 'private2' rewires every subsequent file access with no other edits.

Summary

The orchestration is small on purpose: one PHP function, one .env flag, one constant. That is the entire surface area that turns a shared-host-friendly Laravel layout into a runtime-switchable blue/green workspace.

A more detailed description of the code used and the method of deploying Laravel web applications is provided in the article Laravel 11+ on a Hosting Server with Dynamic Application Version Switching.

How use .env files in Quasar

Jotcomponents — Mon, 24 Aug 2020 13:03:55 +0000

Many developers especially beginers have problems with proper use of .env file during Quasar application development and build-up.

Quasar recent documentation (for ver.1.13) mentions three methods for using enviroment variables in the application:

CLI inline variables e.g.
QENV=development quasar dev
@quasar/dotenv extension
https://www.npmjs.com/package/@quasar/quasar-app-extension-dotenv
@quasar/qenv extension
https://www.npmjs.com/package/@quasar/quasar-app-extension-qenv

Unfortunatelly despite descriptions in official documentation
https://quasar.dev/quasar-cli/handling-process-env
https://quasar.dev/quasar-cli/quasar-conf-js#Example-setting-env-for-dev%2Fbuild

developers are confused in many cases when they try to use .env file due to missing important information in Quasar ducumentation. In this article I want to clarify how proper to use the enviromental variables.

Two basic use cases

Because of different scope of operation we can split the described methods in two groups:

applicable in quasar.conf.js (main configuration file):
- CLI inline variables
- @quasar/dotenv extension
applicable ONLY in the application (boot files, components):
- @quasar/qenv extension

Most important conclusion here is

You cannot use @quasar/qenv extension for settings in quasar.conf.js

How to use @quasar/dotenv extension

Very good description is in article
https://medium.com/carbono/using-env-file-in-quasar-apps-72b56909302f

At first install Quasar App Extension dotenv:
https://www.npmjs.com/package/@quasar/quasar-app-extension-dotenv

quasar ext add @quasar/dotenv

then create new js file envparser.js in /src/config:

const DotEnv = require('dotenv')
const parsedEnv = DotEnv.config().parsed
module.exports = function () {
  // Let's stringify our variables
  for (key in parsedEnv) {
    if (typeof parsedEnv[key] === 'string') {
      parsedEnv[key] = JSON.stringify(parsedEnv[key])
    }
  }
  return parsedEnv
}

in quasar.conf.js then include on the most top of the file following code:

const envparser = require('./src/config/envparser.js')

and assign this function to (new) env variable to the build attribute in quasar.conf.js:

build: {
  env: envparser(),
  vueRouterMode: 'history',
...}

Create a file .env in the top (root) project directory. It can contain any number of custom env variables e.g.

JOT_PUBLIC_PATH=http://dev.com/flexbox/dist/spa

then you use the variable in quasar.config.js

build: {
     env: envparser(),
     vueRouterMode: 'history',
     publicPath: ctx.prod ? process.env.JOT_PUBLIC_PATH : '',
...}

In object process.env are available all server/computer environment variables and all custom environment variables from .env file.

How to use @quasar/qenv extension

Install Quasar extension

quasar ext add @quasar/qenv

File .quasar.env.json is created during installation with demo template

{
  "development": {
    "ENV_TYPE": "Running Development",
    "ENV_DEV": "Development"
  },
  "production": {
    "ENV_TYPE": "Running Production",
    "ENV_PROD": "Production"
  },
  "test": {
    "ENV_TYPE": "Running Test",
    "ENV_Test": "Test"
  }
}

Variables from .quasar.env.json are available only after successfull application build (i.e. after processing quasar.config.js). These custom variables together with some other built-in variables are available in the application boot files, application and components files.

In object process.env are available only variables from .quasar.env.json and Quasar built-in environment variables.

Using above defined template the process.env object contains:

{
      "ENV_TYPE": "Running Development",
      "ENV_DEV": "Development",
      "NODE_ENV": "development",
      "CLIENT": true,
      "SERVER": false,
      "DEV": true,
      "PROD": false,
      "MODE": "spa",
      "VUE_ROUTER_MODE": "hash",
      "VUE_ROUTER_BASE": "",
      "APP_URL": "http://localhost:8080"
}

After build processing the server/computer environment variables are NOT AVAILABLE in new created process.env object.

Example use in boot file:

export default async (app /* { app, router, Vue ... } */) => {
 console.log('show router mode:', process.env.VUE_ROUTER_MODE);
 // something to do
}

Example use in *.vue file:

<script>
  console.log('inside', process.env.VUE_ROUTER_MODE);
  export default {
    name: 'App',
  }
</script>