Skip to content

suggestions.md

Latest commit

 

History

History
256 lines (197 loc) · 7.9 KB

suggestions.md

File metadata and controls

256 lines (197 loc) · 7.9 KB

Recommended Next Steps & Improvements

This document provides a set of recommended enhancements to turn this base Laravel template into a more feature-complete and productive starting point for a new project.

1. Development Environment Enhancements

These changes improve the day-to-day development experience within VS Code and are highly recommended.

a) Automate Common Tasks

Create a .vscode/tasks.json file to run common commands like tests and linters directly from the VS Code Command Palette, saving you from typing them in the terminal.

Action: Create a new file at .vscode/tasks.json with the following content:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Serve: Start Laravel Server",
            "type": "shell",
            "command": "php artisan serve",
            "group": "run",
            "isBackground": true,
            "problemMatcher": []
        },
        {
            "label": "Test: Run All Tests (PHPUnit)",
            "type": "shell",
            "command": "php artisan test",
            "group": "test",
            "presentation": {
                "reveal": "always",
                "panel": "new"
            }
        },
        {
            "label": "Fix: Run Code Styler (Pint)",
            "type": "shell",
            "command": "vendor/bin/pint",
            "group": "build",
            "presentation": {
                "reveal": "never"
            }
        }
    ]
}

b) Add More VS Code Extensions

Add these widely-used extensions to your .devcontainer/devcontainer.json file for better Git integration and code consistency.

Action: Add the following lines to the extensions array in .devcontainer/devcontainer.json:

// ... inside "customizations.vscode.extensions"
"eamodio.gitlens",
"EditorConfig.EditorConfig",
"ms-azuretools.vscode-docker"

2. Laravel Application Enhancements

These changes add core features to the Laravel application itself.

a) Add User Authentication (Highly Recommended)

The most valuable addition to a new application is a complete authentication system. Laravel Breeze provides a simple, secure, and fully-featured scaffold for logins, registration, password resets, and more.

Action: Run the following commands in the Codespace terminal to install Laravel Breeze with the Blade stack:

  1. Require Breeze:

    composer require laravel/breeze --dev

  2. Install the Blade scaffold:

    php artisan breeze:install blade

  3. Install frontend dependencies:

    npm install

  4. Compile assets and run database migrations:

    npm run build
php artisan migrate

After running these commands, your application will have a complete and working user authentication system.

b) Enforce Consistent Code Style

Your project already includes Laravel Pint, a code style fixer. To make it easy for everyone on the team to use, you can add a script to your composer.json file.

Action: Add the following lint script to the scripts section of your composer.json file:

// ... inside composer.json
"scripts": {
    "post-autoload-dump": [
        "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
        "@php artisan package:discover --ansi"
    ],
    "post-update-cmd": [
        "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
    ],
    "post-root-package-install": [
        "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
    ],
    "post-create-project-cmd": [
        "@php artisan key:generate --ansi",
        "@php -r \"if (file_exists('database/database.sqlite')) { copy('database/database.sqlite', 'database/database.sqlite.example'); }\""
    ],
    "lint": [
        "vendor/bin/pint"
    ]
},

Now, any developer can run composer lint to automatically format the code according to Laravel's standard.

c) Consider User Roles & Permissions

For applications that require different types of users (e.g., admin, user), it's a good practice to add a role system early.

Action (Simple Implementation):

  1. Create a migration to add a role column to your users table: 
    php artisan make:migration add_role_to_users_table --table=users
  2. In the new migration file, add a string column for the role with a default value: 
    // In the up() method
Schema::table('users', function (Blueprint $table) {
    $table->string('role')->default('user');
});
  3. Run the migration: 
    php artisan migrate

This provides a basic foundation for checking user roles that you can build upon with middleware or policies.

3. Advanced Improvements

These suggestions are for setting up a professional-grade, robust application workflow. They involve more configuration but provide significant benefits for code quality and stability.

a) Set Up Continuous Integration (CI)

A CI pipeline will automatically run your tests and linter on every push and pull request, ensuring the main branch of your repository is always stable.

Action: Create a new workflow file at .github/workflows/ci.yml with the following content:

name: Run Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite
          coverage: none

      - name: Install Composer dependencies
        run: composer install --prefer-dist --no-progress --no-suggest

      - name: Prepare Laravel Application
        run: |
          cp .env.example .env
          php artisan key:generate

      - name: Run Code Linter (Pint)
        run: vendor/bin/pint --test

      - name: Run Tests (PHPUnit)
        run: php artisan test

b) Integrate Static Analysis

Static analysis tools find bugs and potential errors in your code before you even run it. The most popular tool for Laravel is Larastan.

Action: Add Larastan to your project and create a default configuration file.

  1. Require Larastan: 
    composer require nunomaduro/larastan --dev
  2. Create a configuration file named phpstan.neon in your project root: 
    includes:
    - ./vendor/nunomaduro/larastan/extension.neon

parameters:
    paths:
        - app/
    level: 5
  3. Add a stan script to your composer.json to make it easy to run: 
    // ... inside composer.json scripts
"stan": [
    "vendor/bin/phpstan analyse"
]

c) Configure a Separate Testing Database

To protect your development data, you should configure your tests to run against a separate, isolated database. Using an in-memory SQLite database is the fastest and most common approach for testing.

Action: Modify your phpunit.xml file to use an in-memory SQLite database for tests.

  1. Open phpunit.xml.

  2. Uncomment the DB_CONNECTION and DB_DATABASE variables and set their values as shown below:

    <!-- In phpunit.xml -->
<php>
    <env name="APP_ENV" value="testing"/>
    <env name="BCRYPT_ROUNDS" value="4"/>
    <env name="CACHE_DRIVER" value="array"/>
    <!-- <env name="DB_CONNECTION" value="sqlite"/> -->
    <!-- <env name="DB_DATABASE" value=":memory:"/> -->
    <env name="DB_CONNECTION" value="sqlite"/>
    <env name="DB_DATABASE" value=":memory:"/>
    <env name="MAIL_MAILER" value="array"/>
    <env name="QUEUE_CONNECTION" value="sync"/>
    <env name="SESSION_DRIVER" value="array"/>
    <env name="TELESCOPE_ENABLED" value="false"/>
</php>

Now, when you run php artisan test, it will use a fresh, in-memory database every time, ensuring your tests are fast and isolated.