Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (78 loc) · 4.2 KB

AGENTS.md

File metadata and controls

117 lines (78 loc) · 4.2 KB

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Project Overview

This is the official Lando plugin for Laravel (@lando/laravel). It provides a recipe that configures PHP, web server, database, and caching services for Laravel development environments.

Common Commands

# Install dependencies
npm install

# Run linting
npm run lint

# Run unit tests
npm run test:unit

# Run both lint and unit tests
npm test

# Run integration tests (Leia)
npm run test:leia

# Run a single integration test
npx leia examples/laravel-defaults/README.md -c 'Destroy tests'

# Documentation development
npm run docs:dev      # Start dev server
npm run docs:build    # Build docs

Architecture

Plugin Structure

  • builders/ - Service builders that extend Lando's base services

    • laravel.js - Main recipe builder, configures all services and tooling
    • laravel-php.js, laravel-nginx.js, laravel-mysql.js, etc. - Service-specific builders that extend @lando/php, @lando/mysql, etc.

  • config/ - Configuration templates

    • default.conf.tpl - Nginx vhost template
    • php.ini, mysql.cnf, mysql8.cnf - Service configs

  • inits/ - Initialization logic for lando init command

  • examples/ - Working Lando apps for development and testing. Each example has a plugins: "@lando/laravel": ../.. directive to use the local source.

  • test/ - Unit tests (Mocha/Chai). Name files as *.spec.js.

Recipe Configuration Flow

The main builders/laravel.js exports a recipe that:

  1. Accepts user config (php version, database type, cache, via, webroot, xdebug)
  2. Merges defaults with user overrides
  3. Configures services: appserver (PHP), database, optional cache
  4. Sets up tooling: composer, php, artisan, db-import/export, database CLI

Dependencies

This plugin depends on other Lando service plugins:

  • @lando/php - PHP/Apache/Nginx services
  • @lando/mysql, @lando/mariadb, @lando/postgres, @lando/mssql - Databases
  • @lando/redis, @lando/memcached - Caching

Testing

Unit Tests

Place in test/ with .spec.js extension. Run with npm run test:unit.

Leia Integration Tests

Integration tests are written as shell commands in markdown (example READMEs). The markdown follows a specific format with "Start up tests", "Verification commands", and "Destroy tests" sections. See examples/*/README.md for examples.

Note: Integration tests in examples/ are run by the pr-laravel-tests.yml GitHub Actions workflow on pull requests, but only if they are explicitly listed in the workflow's test matrix. New examples must be added to the matrix in pr-laravel-tests.yml to be included in CI.

GitHub Actions

CI/CD workflows are defined in .github/workflows/:

PR Workflows (run on every pull request)

Workflow File Purpose
Laravel Tests pr-laravel-tests.yml Runs Leia integration tests for examples explicitly listed in the workflow matrix. Tests against Lando 3-edge and 3-stable on Ubuntu.
Unit Tests pr-unit-tests.yml Runs npm run test:unit across Windows, Ubuntu, and macOS.
Lint Code pr-linter.yml Runs npm run lint to check code style.
Docs Tests pr-docs-tests.yml Builds documentation to verify no broken builds.

Release Workflow

Workflow File Purpose
Publish to NPM release.yml Triggered on GitHub release creation. Runs lint + unit tests, then publishes to npm. Stable releases go to latest tag; prereleases go to edge tag.

Integration Test Matrix

The pr-laravel-tests.yml workflow explicitly lists which examples to test. New examples must be added to this list to run in CI.

Each test runs against the example's README.md using the Leia test runner.

Development Workflow

  1. Use examples directory - apps there reference the local plugin source
  2. To test against an external app, add to its Landofile: 
    plugins:
  "@lando/laravel": /path/to/this/plugin

Code Style

  • ESLint with Google config, max 140 char lines
  • Node.js 20+
  • JSDoc required for function declarations
  • 2-space indentation