README

A smart Laravel Artisan command for serving your application on the first available port with automatic browser opening.

📋 Overview

The app:serve command provides an intelligent solution for serving your Laravel application. It automatically finds an available port within a specified range and launches your application server. It can also automatically open your default web browser to the application URL.

✨ Features

Port Auto-Detection: Automatically finds the first available port in a specified range
Browser Auto-Launch: Opens your default browser to the application URL
Customizable Host: Specify a custom host address to serve your application on
Configurable Port Range: Set your preferred starting port and maximum attempts
Cross-Platform Support: Works on Windows, macOS, and Linux

🚀 Installation

Option 1: Install via Composer (Recommended)

composer require ez-it-solutions/app-serve

That's it! The package will automatically register the command with Laravel.

Compatibility

This package is compatible with Laravel 6.x, 7.x, 8.x, 9.x, and 10.x.

Option 2: Manual Installation

Download the AppServeCommand.php file from our GitHub repository
Place it in your Laravel project at app/Console/Commands/AppServeCommand.php
Laravel's auto-discovery should automatically register the command

📦 Creating Your Own Package

If you want to create your own version of this package, follow these steps:

1. Set Up Package Structure

Create the following directory structure:

app-serve/
├── src/
│   ├── Commands/
│   │   └── AppServeCommand.php
│   └── AppServeServiceProvider.php
├── composer.json
├── LICENSE
└── README.md

2. Create composer.json

{
    "name": "ez-it-solutions/app-serve",
    "description": "A Laravel command for serving your application on the first available port",
    "type": "library",
    "license": "MIT",
    "authors": [
        {
            "name": "Ez IT Solutions",
            "email": "info@ez-it-solutions.com"
        }
    ],
    "require": {
        "php": "^7.3|^8.0"
    },
    "require-dev": {
        "laravel/framework": "^6.0|^7.0|^8.0|^9.0|^10.0"
    },
    "autoload": {
        "psr-4": {
            "Ez_IT_Solutions\\AppServe\\": "src/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Ez_IT_Solutions\\AppServe\\AppServeServiceProvider"
            ]
        }
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

3. Create Service Provider

Create a file at src/AppServeServiceProvider.php:

<?php

namespace Ez_IT_Solutions\AppServe;

use Illuminate\Support\ServiceProvider;
use Ez_IT_Solutions\AppServe\Commands\AppServeCommand;

class AppServeServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        if ($this->app->runningInConsole()) {
            $this->commands([
                AppServeCommand::class,
            ]);
        }
    }

    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        // No additional services to register
    }
}

4. Update Namespace in Command

Update the namespace in your AppServeCommand.php file to match your package:

namespace Ez_IT_Solutions\AppServe\Commands;

5. Publish to GitHub

# Initialize Git repository
git init

# Add all files
git add .

# Commit the files
git commit -m "Initial commit"

# Create a new repository on GitHub at https://github.com/ez-it-solutions/app-serve
# Then push to GitHub
git remote add origin https://github.com/ez-it-solutions/app-serve.git
git branch -M main
git push -u origin main

# Tag a release
git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0

6. Register with Packagist

Visit Packagist
Submit your GitHub repository URL: https://github.com/ez-it-solutions/app-serve
Once approved, your package will be available via Composer

7. Set Up GitHub Webhooks for Packagist

To automatically update your package on Packagist when you push to GitHub:

Go to your GitHub repository settings
Click on "Webhooks" > "Add webhook"
Set Payload URL to: https://packagist.org/api/github?username=your-packagist-username
Set Content type to: application/json
Select "Just the push event"
Click "Add webhook"

8. Add GitHub Actions for Testing (Optional)

Create a file at .github/workflows/tests.yml:

name: Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: [7.4, 8.0, 8.1, 8.2]
        laravel: [8.*, 9.*, 10.*]
        exclude:
          - php: 7.4
            laravel: 10.*

    name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}

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

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" --no-interaction --no-update
          composer update --prefer-dist --no-interaction --no-progress

📝 Usage

Basic Usage

php artisan app:serve

This will start the application server on the first available port starting from 8001.

Custom Host

php artisan app:serve --host=192.168.1.100

This will serve the application on the specified host address.

Custom Port Range

php artisan app:serve --start-port=3000 --max-attempts=5

This will try ports 3000 through 3004 until it finds an available one.

Without Browser Auto-Launch

php artisan app:serve --no-open

This will start the server without automatically opening the browser.

🔧 Customization

Modifying Port Range

You can easily customize the default port range by modifying the $signature property in the command:

protected $signature = 'app:serve 
    {--host=127.0.0.1 : The host address to serve the application on}
    {--start-port=8001 : The starting port number to try}
    {--max-attempts=10 : Maximum number of ports to try}
    {--no-open : Do not open the browser automatically}';

Enhancing Browser Opening Logic

You can customize the browser opening logic by modifying the openBrowser() method:

protected function openBrowser($url)
{
    if (PHP_OS_FAMILY === 'Windows') {
        // Use 'start /B' to start the process in the background without a new window
        shell_exec('start "" /B ' . escapeshellarg($url));
    } elseif (PHP_OS_FAMILY === 'Darwin') {
        // On macOS, use 'open' with the URL
        shell_exec('open ' . escapeshellarg($url));
    } else {
        // On Linux, use 'xdg-open' with the URL
        shell_exec('xdg-open ' . escapeshellarg($url) . ' > /dev/null 2>&1 &');
    }
}

Changing the Command Name

If you want to change the command name, modify the $signature property:

protected $signature = 'your:serve {--host=127.0.0.1 : The host address to serve the application on}';

📊 Output Example

Checking if port 8001 is available...
Serving application on http://127.0.0.1:8001
Press Ctrl+C to stop the server

Starting Laravel development server: http://127.0.0.1:8001
[Wed Sep 7 15:45:23 2025] PHP 8.2.0 Development Server (http://127.0.0.1:8001) started
[Wed Sep 7 15:45:24 2025] [200]: /favicon.ico
[Wed Sep 7 15:45:25 2025] [200]: /css/app.css
[Wed Sep 7 15:45:25 2025] [200]: /js/app.js

The command will automatically open your default web browser to http://127.0.0.1:8001 (or whichever port was available).

💡 Upcoming Features

We're planning to add the following features in future releases:

HTTPS Support

Enable HTTPS with self-signed certificates for local development:

php artisan app:serve --https

Environment-Specific Configuration

Specify which environment file to load:

php artisan app:serve --env=testing

Custom Document Root

Specify a custom document root directory:

php artisan app:serve --docroot=public_html

Specific Browser Selection

Open a specific browser instead of the default one:

php artisan app:serve --browser=chrome

QR Code Display

Generate and display a QR code in the terminal for easy mobile testing:

php artisan app:serve --qr

Multiple Host Binding

Bind to multiple interfaces simultaneously:

php artisan app:serve --hosts=127.0.0.1,192.168.1.100

Auto-Reload on File Changes

Watch for file changes and reload the browser automatically:

php artisan app:serve --watch
php artisan app:serve --watch-dir=resources/views

Performance Metrics

Display basic performance metrics for requests:

php artisan app:serve --metrics

Request Logging

Enhanced request logging with filtering options:

php artisan app:serve --log-requests --log-level=debug

API Testing Mode

Optimize output for API development:

php artisan app:serve --api-mode

Custom Server Headers

Add custom headers to all responses:

php artisan app:serve --header="X-Custom: Value"

🤝 Contributing

Contributions are welcome! Feel free to submit a pull request or open an issue.

📄 License

This project is open-sourced software licensed under the MIT license.

👨‍💻 Author

Ez IT Solutions
https://github.com/ez-it-solutions

ez-it-solutions / app-serve

Maintainers

Details