concept-image/wp-acorn-stubs

Add commands to generate action class file, service class file, enum file, interface file, trait file, and value object class file. This package should be installed as a dev dependency.

1.0.1 2025-09-29 16:56 UTC

Requires

• php: ^8.2
• roots/acorn: >=4.3

Suggests

• This package should be installed as a dev dependency: composer require --dev concept-image/wp-acorn-stubs

MIT

• Aurélien Cellier

README

A comprehensive collection of Artisan commands for generating clean, well-structured PHP classes in WordPress projects using Roots Acorn. This package follows Laravel best practices and helps you create maintainable, testable code by encouraging proper separation of concerns and design patterns.

🚀 Features

• Action Classes: Single-responsibility command classes for business logic
• Service Classes: Reusable service layer components
• Interface Classes: Contract definitions for better architecture
• Trait Classes: Reusable code snippets across classes
• Enum Classes: Type-safe enumeration support (PHP 8.1+)
• Value Object Classes: Immutable data containers
• Helper Classes: Static utility functions

📋 Requirements

• PHP 8.2 or higher
• Roots Acorn 4.3 or higher
• WordPress project with Acorn framework

🔧 Installation

This package should be installed as a development dependency:

composer require --dev concept-image/wp-acorn-stubs

The service provider will be automatically registered via Acorn's auto-discovery feature.

📖 Usage

All commands are available through the wp acorn CLI. Run commands from your theme directory:

Available Commands

Command	Description	Namespace
make:action	Create single-responsibility action classes	App\Actions
make:service	Create service layer classes	App\Services
make:interface	Create interface contracts	App\Interfaces
make:trait	Create reusable trait classes	App\Traits
make:enum	Create type-safe enumerations	App\Enums
make:value-object	Create immutable value objects	App\ValueObjects
make:helper	Create static utility helper classes	App\Helpers

Quick Examples

# Basic usage
wp acorn make:action SendWelcomeEmail
wp acorn make:service PaymentService
wp acorn make:interface CacheInterface
wp acorn make:trait Loggable
wp acorn make:enum UserStatus
wp acorn make:value-object Money
wp acorn make:helper StringHelper

# With presets (smart detection)
wp acorn make:enum PaymentStatus     # Suggests payment preset
wp acorn make:value-object Email     # Suggests email preset

# Explicit preset usage
wp acorn make:enum OrderStatus --preset=status
wp acorn make:value-object Price --preset=money

Action Classes

Generate single-responsibility action classes that encapsulate business logic:

wp acorn make:action SendWelcomeEmail

Generated file: app/Actions/SendWelcomeEmailAction.php

<?php

declare(strict_types=1);

namespace App\Actions;

final readonly class SendWelcomeEmailAction
{
    /**
     * Execute the action.
     */
    public function handle(): void
    {
        //
    }
}

Best Practice Usage:

// In a controller or service
$action = new SendWelcomeEmailAction();
$action->handle();

// Or with dependency injection
app(SendWelcomeEmailAction::class)->handle();

Service Classes

Create service layer classes for complex business logic and external integrations:

wp acorn make:service PaymentService

Generated file: app/Services/PaymentServiceService.php

<?php

declare(strict_types=1);

namespace App\Services;

final readonly class PaymentServiceService
{
    //
}

Best Practice Usage:

class PaymentService
{
    public function __construct(
        private readonly HttpClient $client,
        private readonly LoggerInterface $logger
    ) {}

    public function processPayment(array $data): PaymentResult
    {
        // Complex payment processing logic
    }
}

Interface Classes

Generate interfaces to define contracts and improve testability:

wp acorn make:interface PaymentGatewayInterface

Generated file: app/Interfaces/PaymentGatewayInterfaceInterface.php

<?php

declare(strict_types=1);

namespace App\Interfaces;

interface PaymentGatewayInterfaceInterface
{
    //
}

Best Practice Usage:

interface PaymentGatewayInterface
{
    public function charge(Money $amount, PaymentMethod $method): PaymentResult;
}

class StripeGateway implements PaymentGatewayInterface
{
    // Implementation
}

Trait Classes

Create reusable trait classes for shared functionality:

wp acorn make:trait Cacheable

Generated file: app/Traits/CacheableTrait.php

<?php

declare(strict_types=1);

namespace App\Traits;

trait CacheableTrait
{
    //
}

Best Practice Usage:

trait Loggable
{
    protected function log(string $message, array $context = []): void
    {
        logger()->info($message, $context);
    }
}

class UserService
{
    use Loggable;

    public function createUser(array $data): User
    {
        $this->log('Creating new user', ['email' => $data['email']]);
        // User creation logic
    }
}

Enum Classes

Generate type-safe enumerations for better code clarity:

wp acorn make:enum UserStatus

Generated file: app/Enums/UserStatusEnum.php

<?php

declare(strict_types=1);

namespace App\Enums;

enum UserStatusEnum: int
{
    case VALUE = 1;
}

Best Practice Usage:

enum UserStatus: string
{
    case ACTIVE = 'active';
    case INACTIVE = 'inactive';

    public function getLabel(): string
    {
        return match($this) {
            self::ACTIVE => 'Active User',
            self::INACTIVE => 'Inactive User',
        };
    }
}

Value Object Classes

Create immutable value objects for data integrity:

wp acorn make:value-object Money

Generated file: app/ValueObjects/Money.php

<?php

declare(strict_types=1);

namespace App\ValueObjects;

final class Money
{
    //
}

Best Practice Usage:

final readonly class Money
{
    public function __construct(
        public int $amount,
        public string $currency
    ) {
        if ($amount < 0) {
            throw new InvalidArgumentException('Amount cannot be negative');
        }
    }

    public function add(Money $other): Money
    {
        if ($this->currency !== $other->currency) {
            throw new InvalidArgumentException('Currency mismatch');
        }

        return new Money($this->amount + $other->amount, $this->currency);
    }
}

Helper Classes

Generate helper classes for static utility functions:

wp acorn make:helper StringHelper

Generated file: app/Helpers/StringHelper.php

<?php

declare(strict_types=1);

namespace App\Helpers;

final readonly class StringHelper
{
    // Use static function in helper class
}

Best Practice Usage:

final class StringHelper
{
    public static function slugify(string $text): string
    {
        return strtolower(trim(preg_replace('/[^A-Za-z0-9-]+/', '-', $text)));
    }

    public static function truncate(string $text, int $length = 100): string
    {
        return strlen($text) > $length ? substr($text, 0, $length) . '...' : $text;
    }
}

📁 Generated File Structure

app/
├── Actions/
│   ├── SendWelcomeEmailAction.php
│   └── ProcessPaymentAction.php
├── Enums/
│   ├── UserStatus.php
│   └── PaymentStatus.php
├── Helpers/
│   ├── StringHelperHelper.php
│   └── ArrayHelperHelper.php
├── Interfaces/
│   ├── PaymentGatewayInterface.php
│   └── CacheInterface.php
├── Services/
│   ├── PaymentService.php
│   └── EmailService.php
├── Traits/
│   ├── CacheableTrait.php
│   └── LoggableTrait.php
└── ValueObjects/
    ├── Money.php
    └── Email.php

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Credits

• Author: Aurélien Cellier
• Inspired by: Laravel Best Practices
• Framework: Roots Acorn

📚 Further Reading

• Laravel Best Practices Guide
• Controller Refactoring Techniques
• SOLID Principles in PHP
• Value Objects in PHP