Module Management

Install, enable, disable, and manage ZephyrPHP modules to extend your application with powerful features like database ORM, authentication, caching, and more.

Module System Overview

ZephyrPHP's modular architecture allows you to add functionality as needed, keeping your application lean and maintainable. Modules are distributed as Composer packages and can be enabled or disabled without removing code.

Available Official Modules

add - Install and Enable Module

Install a ZephyrPHP module via Composer and automatically enable it in your application.

php craftsman add [module]

Arguments

Examples

# Install database module
php craftsman add database

# Install authentication module
php craftsman add auth

# Install cache module
php craftsman add cache

# Install authorization module
php craftsman add authorization

# Install API module
php craftsman add api

Installation Process

$ php craftsman add database

Installing database module...

1. Checking Composer availability... ✓
2. Running composer require zephyrphp/database... ✓
3. Registering module in config/modules.php... ✓
4. Running module installation hooks... ✓
5. Publishing configuration files... ✓

✓ Database module installed and enabled successfully!

Next steps:
- Configure database in .env file
- Run: php craftsman db:setup
- Run: php craftsman db:create

What Happens During Installation

1. Composer Installation

• Downloads module package from Packagist
• Installs dependencies
• Updates composer.json and composer.lock

2. Module Registration

• Adds module to config/modules.php
• Sets module status to "enabled"
• Registers service providers

3. Configuration Publishing

• Copies default config files to config/
• Creates necessary directories in storage/
• Publishes assets if applicable

4. Post-Install Hooks

• Runs module-specific installation tasks
• Creates database migrations if needed
• Displays post-installation instructions

Module-Specific Installation

Database Module

$ php craftsman add database

Installing database module...
✓ Installed zephyrphp/database
✓ Published config/database.php
✓ Created storage/migrations/

Next steps:
1. Configure database connection:
   php craftsman db:setup

2. Create database:
   php craftsman db:create

3. Create your first model:
   php craftsman model:wizard

Auth Module

$ php craftsman add auth

Installing auth module...
✓ Installed zephyrphp/auth
✓ Published config/auth.php
✓ Created src/Middleware/AuthMiddleware.php

Next steps:
1. Configure authentication:
   php craftsman auth:setup

2. Add auth routes (login, register, logout)
3. Apply AuthMiddleware to protected routes

Cache Module

$ php craftsman add cache

Installing cache module...
✓ Installed zephyrphp/cache
✓ Published config/cache.php
✓ Created storage/cache/

Next steps:
1. Configure cache driver in .env:
   CACHE_DRIVER=file (or redis, memcached)

2. Use cache in your code:
   Cache::put('key', 'value', 3600);

module:list - List All Modules

Display all available and installed modules with their status, version, and description.

php craftsman module:list [options]

Options

Examples

# List all modules
php craftsman module:list

# Show only enabled modules
php craftsman module:list --enabled

# Show only disabled modules
php craftsman module:list --disabled

# Show available modules to install
php craftsman module:list --available

Example Output

$ php craftsman module:list

Installed Modules
=================

+----------------+-----------+---------+------------------------------------------+
| Module         | Version   | Status  | Description                              |
+----------------+-----------+---------+------------------------------------------+
| database       | 0.1.0     | Enabled | Doctrine ORM and database management     |
| auth           | 0.1.0     | Enabled | Session and JWT authentication           |
| cache          | 0.1.0     | Disabled| Redis, Memcached, and file caching       |
| authorization  | 0.1.0     | Disabled| Role-based access control                |
+----------------+-----------+---------+------------------------------------------+

Available Modules
=================

+----------------+------------------------------------------+
| Module         | Description                              |
+----------------+------------------------------------------+
| api            | RESTful API utilities and helpers        |
+----------------+------------------------------------------+

Total installed: 4 (2 enabled, 2 disabled)
Available to install: 1

module:enable - Enable Module

Enable a previously disabled module without reinstalling it.

php craftsman module:enable [module]

Examples

# Enable cache module
php craftsman module:enable cache

# Enable authorization module
php craftsman module:enable authorization

# Enable multiple modules
php craftsman module:enable cache authorization api

Example Output

$ php craftsman module:enable cache

Enabling cache module...
✓ Module enabled successfully!
✓ Service providers registered
✓ Configuration loaded

Cache module is now active.

What Happens When Enabled

• Updates module status in config/modules.php
• Registers service providers with the application
• Loads module configuration
• Makes module features available
• Runs module boot hooks

Common Use Cases

Feature Toggling

# Disable features in development
php craftsman module:disable authorization

# Enable for testing
php craftsman module:enable authorization

# Disable again if not needed
php craftsman module:disable authorization

Environment-Specific

# Production - enable caching
php craftsman module:enable cache

# Development - disable caching for easier debugging
php craftsman module:disable cache

module:disable - Disable Module

Disable a module without removing it from your project. The code remains but features are inactive.

php craftsman module:disable [module]

Examples

# Disable cache module
php craftsman module:disable cache

# Disable authorization module
php craftsman module:disable authorization

# Disable multiple modules
php craftsman module:disable cache authorization

Example Output

$ php craftsman module:disable cache

Disabling cache module...
✓ Module disabled successfully!
✓ Service providers unregistered
✓ Module hooks removed

Cache module is now inactive.

What Happens When Disabled

• Updates module status in config/modules.php
• Unregisters service providers
• Module features become unavailable
• Code remains in vendor/
• Configuration files remain in config/

remove - Uninstall Module

Completely remove a module from your project, including all code and configuration.

php craftsman remove [module]

Examples

# Remove cache module
php craftsman remove cache

# Remove authorization module
php craftsman remove authorization

Example Output

$ php craftsman remove cache

Warning: This will completely remove the cache module.
Continue? [y/N]: y

Removing cache module...
✓ Module disabled
✓ Removing Composer package... ✓
✓ Removing configuration files... ✓
✓ Cleaning up storage directories... ✓
✓ Unregistering from modules.php... ✓

Cache module removed successfully!

Removal Process

1. Confirmation

• Prompts for confirmation (destructive operation)
• Warns about dependencies

2. Disable Module

• Disables module first
• Unregisters service providers

3. Remove Package

• Runs composer remove zephyrphp/module
• Removes from composer.json
• Deletes package from vendor/

4. Cleanup

• Optionally removes configuration files
• Optionally cleans storage directories
• Removes from config/modules.php

module:info - Module Information

Display detailed information about a specific module, including version, status, dependencies, and configuration.

php craftsman module:info [module]

Examples

# Show database module info
php craftsman module:info database

# Show auth module info
php craftsman module:info auth

Example Output

$ php craftsman module:info database

Database Module
===============

Package:        zephyrphp/database
Version:        0.1.0
Status:         Enabled
Installed:      2024-01-15 10:23:45

Description:
Doctrine ORM integration with query builder, migrations, and schema management.

Features:
- Doctrine ORM entity management
- Database query builder
- Schema migrations
- Multiple database connections
- Repository pattern support

Dependencies:
- doctrine/orm: ^2.14
- doctrine/dbal: ^3.6

Configuration Files:
- config/database.php

Service Providers:
- DatabaseServiceProvider
- DoctrineServiceProvider

Commands:
- db:setup
- db:create
- db:test
- db:schema
- make:model
- model:wizard
- model:build

Documentation:
https://zephyrphp.com/docs/database

Module Management Workflow

Fresh Project Setup

# 1. Install ZephyrPHP
composer create-project zephyrphp/starter my-project

# 2. Generate app key
php craftsman key:generate

# 3. Install database module
php craftsman add database

# 4. Configure database
php craftsman db:setup

# 5. Install authentication
php craftsman add auth

# 6. Configure auth
php craftsman auth:setup

# 7. Start developing
php craftsman serve

Adding Features to Existing Project

# 1. Check available modules
php craftsman module:list --available

# 2. Install desired module
php craftsman add cache

# 3. Configure the module
# Edit config/cache.php or use module setup command

# 4. Enable module (if not auto-enabled)
php craftsman module:enable cache

# 5. Use the new features in your code

Testing/Debugging Modules

# 1. Disable module to isolate issue
php craftsman module:disable authorization

# 2. Test without the module
php craftsman serve

# 3. Re-enable if needed
php craftsman module:enable authorization

# 4. Or remove completely if not needed
php craftsman remove authorization

Custom Module Development

Creating Your Own Module

You can create custom modules for your organization:

Module Structure

my-module/
├── composer.json
├── src/
│   ├── ModuleServiceProvider.php
│   ├── Commands/
│   ├── Controllers/
│   └── Models/
├── config/
│   └── my-module.php
└── README.md

composer.json

{
    "name": "your-org/my-module",
    "description": "Custom ZephyrPHP module",
    "type": "library",
    "require": {
        "php": "^8.1",
        "zephyrphp/framework": "^0.1"
    },
    "autoload": {
        "psr-4": {
            "YourOrg\\MyModule\\": "src/"
        }
    },
    "extra": {
        "zephyrphp": {
            "providers": [
                "YourOrg\\MyModule\\ModuleServiceProvider"
            ]
        }
    }
}

Service Provider

<?php

namespace YourOrg\MyModule;

use ZephyrPHP\Core\ServiceProvider;

class ModuleServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register services
    }

    public function boot(): void
    {
        // Boot module
        $this->publishes([
            __DIR__.'/../config/my-module.php' => config_path('my-module.php'),
        ], 'config');
    }
}

Installing Custom Modules

# From local path
composer require your-org/my-module --prefer-source

# From private repository
composer config repositories.my-module vcs https://github.com/your-org/my-module
composer require your-org/my-module

# Register in config/modules.php
php craftsman module:enable my-module

Troubleshooting

Installation Failed

Composer Not Found

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Verify installation
composer --version

Network Issues

# Check internet connection
ping packagist.org

# Clear Composer cache
composer clear-cache

# Retry installation
php craftsman add database

Version Conflicts

# View dependency issues
composer why-not zephyrphp/database

# Update dependencies
composer update

# Try installation again
php craftsman add database

Module Not Working After Installation

Clear Cache

php craftsman cache:clear

Verify Module is Enabled

php craftsman module:list --enabled

Check Configuration

# Ensure config file exists
ls config/database.php

# Verify .env settings
cat .env | grep DB_

Regenerate Autoloader

composer dump-autoload

Cannot Disable Module

Dependency Conflict

# Check which modules depend on this one
php craftsman module:info cache

# Disable dependent modules first
php craftsman module:disable authorization
php craftsman module:disable cache

Best Practices

Module Selection

• Install only what you need: Keep your application lean
• Review module documentation: Understand features before installing
• Check compatibility: Ensure module works with your PHP/framework version
• Consider alternatives: Compare similar modules before choosing

Version Control

# Commit composer.json and composer.lock
git add composer.json composer.lock
git commit -m "Add database module"

# Don't commit vendor/
echo "vendor/" >> .gitignore

# Document module choices
# Add to README.md why each module was chosen

Production Deployment

# Install modules with production optimizations
composer install --no-dev --optimize-autoloader

# Enable only required modules
php craftsman module:list --enabled

# Disable dev-only modules
php craftsman module:disable debug-bar

Next Steps

Learn more about ZephyrPHP features:

• Set up security with Authentication Commands
• Create your own tools with Custom Commands
• Manage your database with Database Commands
• Return to Craftsman CLI Overview