Scriptsdev Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your project via Composer:

   composer require neronmoon/scriptsdev --dev
   

   The package registers a custom Composer script directive (scripts-dev) automatically.

2. First Use Case Define a scripts-dev section in your composer.json to run development-specific tasks:

   {
       "scripts-dev": {
           "test": "phpunit",
           "lint": "php-cs-fixer fix --dry-run"
       }
   }
   

   Run them via:

   composer scripts-dev
   

3. Where to Look

   • Check composer.json for the scripts-dev section.
   • Review composer.json for existing scripts vs. scripts-dev separation.
   • Default behavior: Runs all tasks in scripts-dev unless specified otherwise.

Implementation Patterns

Workflow Integration

1. Parallel with scripts Use scripts for production tasks (e.g., dump-autoload) and scripts-dev for dev-only tasks (e.g., lint, test). Example:

   {
       "scripts": {
           "build": "npm run build"
       },
       "scripts-dev": {
           "test": "phpunit",
           "watch": "npm run dev"
       }
   }
   

2. Conditional Execution Combine with Composer’s --no-dev flag or custom scripts to toggle dev tasks:

   composer scripts-dev test  # Runs only 'test'
   composer scripts-dev       # Runs all dev scripts
   

3. Laravel-Specific Patterns

   • Artisan Wrappers: Alias scripts-dev tasks to Artisan commands for consistency:

     "scripts-dev": {
         "migrate:fresh": "php artisan migrate:fresh --seed"
     }
     

   • Task Chaining: Chain dev tasks with && or use composer run for complex workflows:

     composer scripts-dev test && composer scripts-dev lint
     

4. Environment Awareness Use environment variables (e.g., .env) to conditionally enable/disable tasks:

   "scripts-dev": {
       "debug": "php artisan tinker",
       "debug:only-if": "APP_DEBUG=true php artisan tinker"
   }
   

Gotchas and Tips

Pitfalls

1. No Default Task Grouping Unlike scripts, scripts-dev does not auto-group tasks under composer run-script. Always prefix with scripts-dev:

   composer scripts-dev test  # Correct
   composer test              # Fails (unless aliased)
   

2. Order Dependency Tasks run in alphabetical order by default. Use composer run-script with explicit ordering:

   composer run-script scripts-dev test lint
   

3. Dev Mode Only Tasks in scripts-dev ignore --no-dev and will fail if run in production. Test locally:

   composer --no-dev scripts-dev  # Still runs dev scripts!
   

4. No Built-in Parallelism Unlike npm run or make, scripts-dev tasks run sequentially. Use & or tools like parallel for concurrency:

   composer scripts-dev test & composer scripts-dev lint
   

Debugging Tips

1. Dry Runs Use set -x in scripts to debug:

   "scripts-dev": {
       "debug": "set -x; php artisan tinker"
   }
   

2. Exit Codes Scripts with non-zero exits will stop further execution. Use || true to ignore failures:

   "scripts-dev": {
       "lint": "php-cs-fixer fix || true"
   }
   

3. Logging Redirect output to files for debugging:

   "scripts-dev": {
       "test:log": "phpunit > test.log 2>&1"
   }
   

Extension Points

1. Custom Directives Extend the package by creating a post-autoload-dump script to dynamically generate scripts-dev:

   "scripts": {
       "post-autoload-dump": "php generate-scripts-dev.php"
   }
   

2. Integration with Laravel Mix/Vite Use scripts-dev to wrap frontend builds:

   "scripts-dev": {
       "dev": "npm run dev",
       "build": "npm run build"
   }
   

3. CI/CD Pipelines Gate scripts-dev tasks in GitHub Actions/GitLab CI:

   # .github/workflows/test.yml
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - run: composer scripts-dev test