Development Environment Setup - McNamara84/ladis GitHub Wiki

This guide provides a step-by-step explanation for installing and setting up the local development environment for LADIS.

Before you can start developing, you'll need to install several tools. Follow this order for a smooth setup experience:

Git can be installed in various ways. Choose one option based on your comfort level. The Downloads page offers installers for the command-line interface and also GUI applications.

PHP is the core programming language for this project. As with many tools, the installation procedure differs depending on your OS. For Windows, prebuilt binaries are available. On Unix and macOS you have to rely on your favorite package manager.

1. Download and install PHP
2. Verify the installation by running php -v in your terminal. You should see a line like this: PHP 8.4.7 (cli) (built: May 6 2025 12:31:58) (NTS)

You must install Node.js before proceeding – this project requires it for frontend asset compilation and build processes.

Node.js is a free, open-source, cross-platform JavaScript runtime environment that allows running JS outside the browser. It comes with NPM, a package and dependency manager that will be installed automatically with Node.js.

1. Download Node.js: Visit the downloads page and choose an LTS (Long Term Support) version
2. Install: Follow the installation instructions for your operating system
3. Verify installation: Open your terminal and run these commands:

   node -v
   npm -v

   You should see version numbers displayed (e.g., v20.11.0 and 10.2.4)

We recommend using Visual Studio Code (VS Code or simply VSC). It's available on many platforms, widely adopted, and offers an extensive extension ecosystem.

Extensions can be installed directly from the Extensions view in VSC (⇧⌘X) or from the Extensions Marketplace.

Once you have your VSC installed, add these extensions for a better development experience:

EditorConfig is a plain-text file with simple declarations for maintaining consistent coding styles between different editors and IDEs.

Install the EditorConfig for Visual Studio Code. VSC will adopt the settings from the configuration file, overriding any options in its own settings.

PHP Tools for Visual Studio Code (PHP Tools) is an extension bundle that provides advanced PHP development features including debugging and IntelliSense. It also integrates support for Composer and Laravel.

The bundled extensions are:

The extension provides complete integration of Composer, a dependency manager for PHP, and Packagist, the main Composer repository. The composer executable itself is downloaded automatically.

IntelliPHP offers AI-assisted intelligent code predictions for PHP.

Xdebug profiles contain information about PHP code performance. PHP Profiler enables inspecting of profile files in VSC and it also highlights hot paths in your code.

These aren't required and are general recommendations to make working with common file types more comfortable in VSC:

• Markdown All in One enhances the built-in language features for markdown editing.
• Even Better TOML makes editing TOML files even better.

Once you have all the prerequisites installed, you can set up the project locally. This process involves cloning the repository and installing the required dependencies.

First, you need to get a local copy of the project. You can do this using Git from the command line or through a GUI application like GitHub Desktop.

1. Open your terminal or command prompt
2. Navigate to the directory where you want to store the project
3. Clone the repository:

   # Replace <URL> with the actual URL!
   git clone <URL>
   cd cleanup-laser-database

1. Open GitHub Desktop
2. Click File → Clone repository
3. Enter the repository URL or search for it if you have access
4. Choose your local path and click Clone

This project uses Composer to manage PHP dependencies. The composer.json file contains all the required packages for the application to run properly.

1. Navigate to the project directory in your terminal
2. Install PHP dependencies:

   composer install

The installation process will:

• Download all PHP packages defined in composer.json
• Create a vendor/ directory with all dependencies
• Generate the Composer autoloader for efficient class loading

The project uses Node.js and NPM for managing frontend assets and build tools.

In the same project directory, install JavaScript dependencies:

npm install

This command will:

• Read the package.json file for dependency definitions
• Download and install all required Node packages
• Create a node_modules/ directory with the dependencies
• Generate or update the package-lock.json file for dependency locking

Laravel provides first-party support for five different databases.

Create the SQLite database by running this command in the project's root directory:

touch database/database.sqlite

SQLite is an in-process library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine. Creating the file is all that's necessary.

In the next step we'll update the Laravel environment and configure the database connection.

Laravel applications use environment files to manage configuration settings that vary between different users and environments (development, staging, production). Per-user settings are store in .env.

1. Copy the example environment file:

   cp .env.example .env

2. Open the .env file in your code editor and configure the database connection.

   DB_CONNECTION=sqlite
   DB_DATABASE=database/database.sqlite

Update the email configuration in your .env file:

MAIL_MAILER=smtp
MAIL_SCHEME=null
MAIL_HOST=MAILSERVERHOST
MAIL_PORT=465
MAIL_USERNAME=MAILSERVERUSERNAME
MAIL_PASSWORD=MAILSERVERPASSWORD
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

You can always use MAIL_MAILER=log instead of a real email server. You'll find the messages in storage/logs/laravel.log.

Laravel requires a unique application key for encryption and security purposes. This key is generated with Artisan, the command line interface included with Laravel.

Generate the application key:

php artisan key:generate

This command will automatically update your .env file with a new APP_KEY value.

Before you can use the application, you need to set up the database structure. Again artisan provides a command for that.

Run the database migrations:

php artisan migrate

This will create all the necessary database tables as defined in the project's migration files.

Laravel includes a built-in development server for local testing.

1. Run the dev server:

   composer run-script dev

2. Navigate to http://localhost:8000

The Laravel server is started by running the following command:

php artisan serve

If you navigate to http://localhost:8000 right now, you'll see an error message complaining that the file public/build/manifest.json is missing. This manifest.json is generated by Vite, the frontend build tool used in our project.

In the package.json file you can see that there are two scripts configured for Vite, build and dev:

1. "build": "vite build": This command will run the build process once.
2. "dev": "vite": This starts the Vite dev server with hot reloading.

This is a pretty common configuration. Run any of those NPM scripts like this:

npm run <script-name>

Instead of starting the two servers (Laravel and Vite) manually, we'll utilize the scripts defined in composer.json.

The dev command executes a Node.js script called dev-server.js. This script automatically reads the current version tag from Git (when available) and exposes it as an environment variable to the development processes. The script then starts Laravel, the queue worker, and Vite in parallel using concurrently. We use this approach because not all contributors have Git installed via command line (some may only use GitHub Desktop), and the logic was becoming too complex for inline composer scripts.

composer run-script dev

You'll see exactly what the command does:

Open your web browser and navigate to http://localhost:8000

If everything is set up correctly, this is what you should be able to see without any errors:

• PHP: Hypertext Preprocessor
• PHP: Downloads
• PHP: Installation and Configuration - Manual
• PHP For Windows: Binaries and sources Releases
• PHP: Installation on macOS - Manual
• PHP: Installation on Unix systems - Manual
• Git
• Git - Downloads
• GitHub Desktop | Simple collaboration from your desktop
• GitHub CLI | Take GitHub to the command line
• Visual Studio Code - Code Editing. Redefined
• Extensions for Visual Studio family of products | Visual Studio Marketplace
• Use extensions in Visual Studio Code
• VSCodium - Open Source Binaries of VSCode
• Open VSX Registry
• EditorConfig
• editorconfig/editorconfig-vscode: EditorConfig extension for Visual Studio Code
• PHP Tools for Visual Studio and VS Code by DEVSENSE
• Laravel - The PHP Framework For Web Artisans
• Composer – Open VSX Registry
• IntelliPHP - AI Autocomplete for PHP – Open VSX Registry
• PHP Profiler – Open VSX Registry
• Composer
• Command-line interface / Commands - Composer
• Packagist
• Xdebug - Debugger and Profiler Tool for PHP
• Markdown and Visual Studio Code
• markdown-all-in-one – Open VSX Registry
• Even Better TOML – Open VSX Registry
• Node.js — Run JavaScript Everywhere
• Node.js — Download Node.js®
• npm | Home
• ECMA-262 - Ecma International
• About remote repositories - GitHub Docs
• Git - Git Configuration
• Command Palette | VS Code User Interface
• Database: Getting Started - Laravel 12.x - The PHP Framework For Web Artisans
• SQLite Home Page
• Configuration - Laravel 12.x - The PHP Framework For Web Artisans
• Artisan Console - Laravel 12.x - The PHP Framework For Web Artisans
• Vite | Next Generation Frontend Tooling
• concurrently - npm
• Environment variable - Wikipedia
• Git - Tagging