wex_addon_dev_php

Version: 12.7.0

wex_addon_dev_php extends the wex CLI with PHP-specific development commands for Composer, Laravel, Symfony, and WordPress services running in Docker containers. It is aimed at PHP developers who manage their apps through wex and need framework-aware automation — dependency wiring, migration runs, lock-file refreshes — executed directly inside the running service containers. The addon registers four workdir types (php, php-package, php-packages-suite, php-symfony) and contributes its commands through the standard PhpAddonManager plugin point.

Table of Contents

• Installation
• Quickstart
• Tests
• Architecture
• Integration in the Suite
• Dependencies
• Versioning & Compatibility Policy
• License
• About us
• Known Limitations & Roadmap
• Status & Compatibility
• Useful Links
• Migration Notes

Installation

pip install wexample-wex-addon-dev-php

Requires Python >=3.10.

Quickstart

Install the package:

pip install wexample-wex-addon-dev-php

The addon's plugin class is in src/wexample_wex_addon_dev_php/php_addon_manager.py:

from wexample_wex_addon_dev_php.php_addon_manager import PhpAddonManager

Passing PhpAddonManager to the wex kernel registers four workdir types — php, php-package, php-packages-suite, php-symfony — and auto-discovers every service command under services/.

One ready-to-use command is symfony/service/deploy, defined in src/wexample_wex_addon_dev_php/services/symfony/commands/service/deploy.py. When wex invokes it against a running Symfony container it executes:

cd /var/www/html
if [ -d migrations ]; then
  bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration
fi

Pending Doctrine migrations are applied; if there are none, the command exits cleanly.

Tests

This project uses pytest for testing and pytest-cov for code coverage analysis.

Installation

First, install the required testing dependencies:

.venv/bin/python -m pip install pytest pytest-cov

Basic Usage

Run all tests with coverage:

.venv/bin/python -m pytest --cov --cov-report=html

Common Commands

# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing

Viewing HTML Reports

After generating an HTML report, open htmlcov/index.html in your browser to view detailed line-by-line coverage information.

Coverage Threshold

To enforce a minimum coverage percentage:

.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80

This will cause the test suite to fail if coverage drops below 80%.

Architecture

The addon is a Python package (wexample-wex-addon-dev-php) that plugs into the wex CLI through a single manager class. Its parts are: the entry-point manager, a workdir layer (four types), a set of support types, and a service layer where each PHP framework contributes Docker container definitions and commands.

Entry point

src/wexample_wex_addon_dev_php/php_addon_manager.py is the class the host kernel receives. It extends AbstractAddonManager and does two things: it reports the package module so wex can auto-discover every service command nested under services/, and it declares the four workdir types the addon adds:

return {
    "php": PhpWorkdir,
    "php-package": PhpPackageWorkdir,
    "php-packages-suite": PhpPackagesSuiteWorkdir,
    "php-symfony": PhpSymfonyWorkdir,
}

Workdir layer

The four workdir types form a hierarchy rooted in PhpWorkdir.

PhpWorkdir

src/wexample_wex_addon_dev_php/workdir/php_workdir.py is the base for all PHP projects. It extends CodeBaseWorkdir and WithAiWorkdirMixin. Its prepare_value declares the expected filesystem shape: composer.json (must exist), src/ and tests/ directories (both required), and an optional package.json entry that is included only when the file exists on disk. PHP source files in both directories automatically pick up PhpcsFixerOption. get_app_config_file returns a PhpComposerJsonFile; get_dependency_manifests appends package.json when present so that polyglot apps (Symfony or Laravel with a Node-built frontend) follow composer version syncs. Tests are run via vendor/bin/phpunit; has_tests checks for at least one *Test.php file under tests/.

PhpPackageWorkdir

src/wexample_wex_addon_dev_php/workdir/php_package_workdir.py extends PhpWorkdir and adds the mechanics for an individual distributable Composer library.

Backward-compatibility checking uses a dedicated Docker runner built from src/wexample_wex_addon_dev_php/resources/docker/Dockerfile.roave (PHP 8.4 with roave/backward-compatibility-check installed globally). When classifying a version bump, the workdir mounts the git repository root at /var/www/html and runs roave-backward-compatibility-check --from=<last_tag> inside the container; a non-zero exit promotes the bump to major.

Publishing adds a Packagist-friendly annotated tag (vX.Y.Z) on top of what the base class produces, then pushes to the deployment remote via push_to_deployment_remote.

search_in_codebase walks every PhpFile child recursively; search_imports_in_codebase wraps it with a regex that matches use Vendor\Package\...; and qualified references.

PhpPackagesSuiteWorkdir

src/wexample_wex_addon_dev_php/workdir/php_packages_suite_workdir.py extends FrameworkPackageSuiteWorkdir. It identifies child package directories by the presence of a composer.json file (_child_is_package_directory) and materialises each as a PhpPackageWorkdir. The child package directory name reported to the framework is "composer".

PhpSymfonyWorkdir

src/wexample_wex_addon_dev_php/workdir/php_symfony_workdir.py extends PhpWorkdir. Its apply runs the PHP pass first, then creates a JavascriptWorkdir for the same path and runs its apply pass — covering Symfony apps that ship a Node-built frontend alongside their PHP source.

Support types

PhpComposerJsonFile

src/wexample_wex_addon_dev_php/file/php_composer_json_file.py wraps composer.json as a typed JsonFile via AppDependenciesConfigFileMixin. Its responsibilities:

• get_dependencies_versions reads the require block and returns it as dict[str, str]
• add_dependency_from_string adds or updates a constraint in require or require-dev
• dumps injects the package name (derived from the workdir's vendor and project names) and version at write time
• set_private_registry_packages pins each forge-style composer repository (URL containing /packages/composer) to an only list of private package names, preventing it from masking newer Packagist versions

PhpPackageReadmeContentConfigValue

src/wexample_wex_addon_dev_php/config_value/php_package_readme_config_value.py extends AppReadmeConfigValue and overrides _get_app_description to pull the description field from composer.json before falling back to the generic base logic.

DomainTag

src/wexample_wex_addon_dev_php/const/tags.py declares the five domain tags the addon's commands use: APP_LIFECYCLE, CONFIG, DB, FRAMEWORK, LANGUAGE_PHP. Every @command decorator in this package references one or more of them in its tags= list.

Service layer

Services live under src/wexample_wex_addon_dev_php/services/. Each service has a service.yml, a docker/docker-compose.yml, optional env-specific compose overlays under samples/env/{dev,prod,local}/, and a commands/ sub-tree with Python or YAML command files.

php

Defined in src/wexample_wex_addon_dev_php/services/php/service.yml and src/wexample_wex_addon_dev_php/services/php/docker/docker-compose.yml. The base PHP service: runs dunglas/frankenphp:1.13.0-php8.5.11, mounts the app at /var/www/html, and binds a Caddyfile and a web.ini from the runtime config. The laravel and symfony containers extend this compose service definition. Sample files for the Caddyfile (serving from public/, php_server directive) and web.ini (upload limits, memory limit) are shipped in services/php/samples/.

frankenphp

Defined in src/wexample_wex_addon_dev_php/services/frankenphp/service.yml. A standalone FrankenPHP service with the same image and binding conventions as php, used when the app does not need the php base service name.

composer

Defined in src/wexample_wex_addon_dev_php/services/composer/service.yml. A dedicated Composer container (composer:2.9.7) that mounts the app at /var/www/html and stays alive via tail -f /dev/null. Its PHP is the image's, not the app's, so it runs with COMPOSER_IGNORE_PLATFORM_REQS=1: extensions such as intl are the app container's to have. Its commands are the generic lock-management routines that Laravel and Symfony both call.

laravel

Defined in src/wexample_wex_addon_dev_php/services/laravel/service.yml; extends the php compose service and declares a MySQL dependency. src/wexample_wex_addon_dev_php/services/laravel/app_service.py contributes a workdir filestate requirement: uid 82:82 (www-data in Alpine images) on storage/ and bootstrap/cache/, enforced by get_workdir_contribution.

symfony

Defined in src/wexample_wex_addon_dev_php/services/symfony/service.yml; extends the php compose service. src/wexample_wex_addon_dev_php/services/symfony/app_service.py applies the same uid 82:82 requirement to var/. src/wexample_wex_addon_dev_php/services/symfony/knowledge/entity.md is a static knowledge fragment injected into AI context: it states that every Symfony entity must extend AbstractEntity from wexample-symfony-helpers.

wordpress

Defined in src/wexample_wex_addon_dev_php/services/wordpress/service.yml. Runs wordpress:6.3.1-php8.2-apache plus a wordpress_cli sidecar (wordpress:cli-2.7.1-php8.2) defined in src/wexample_wex_addon_dev_php/services/wordpress/docker/docker-compose.yml. WordPress commands target the sidecar by constructing its container name as {app_project_name}_wordpress_cli.

phpmyadmin

Defined in src/wexample_wex_addon_dev_php/services/phpmyadmin/service.yml. Runs phpmyadmin/phpmyadmin:5.2 on the shared wex_net network; the local env overlay injects PMA_USER and PMA_PASSWORD.

Commands

Composer (generic, reused by Laravel and Symfony)

src/wexample_wex_addon_dev_php/services/composer/commands/service/install_local.py is the shared local-wiring routine. It reads local_packages.php from the runtime config, runs composer install --no-scripts inside the target container, symlinks every local-dev package directory from VENDOR_DEV_DIR/<vendor>/<pkg> into vendor/, then runs composer dump-autoload. The constants APP_DIR = "/var/www/html" and VENDOR_DEV_DIR = "/var/www/vendor-dev" are exported so framework services can import them.

src/wexample_wex_addon_dev_php/services/composer/commands/service/refresh_lock.py runs composer update --no-install --with-all-dependencies <packages> inside the container. --no-install rewrites composer.lock without touching vendor/ (which may hold local development symlinks); --with-all-dependencies allows sibling library constraints to move.

Laravel

src/wexample_wex_addon_dev_php/services/laravel/commands/service/install_local.py clears bootstrap/cache/packages.php and bootstrap/cache/services.php before delegating to composer__service__install_local, then runs php artisan optimize:clear to flush the rebuilt service-provider cache.

src/wexample_wex_addon_dev_php/services/laravel/commands/service/refresh_lock.py delegates to the generic composer and node refresh_lock functions, selecting each by whether the corresponding packages argument is non-empty.

src/wexample_wex_addon_dev_php/services/laravel/commands/maintenance/enable.yml is a YAML command that attaches after app::maintenance/enable and runs php artisan down in the Laravel container. Its mirror, src/wexample_wex_addon_dev_php/services/laravel/commands/maintenance/disable.yml, attaches after app::maintenance/disable and runs php artisan up.

src/wexample_wex_addon_dev_php/services/laravel/commands/db/migrate.yml attaches before app::maintenance/disable and runs php artisan migrate --force --no-interaction -vvv, so migrations complete before the app is brought back up.

Symfony

src/wexample_wex_addon_dev_php/services/symfony/commands/service/install_local.py calls composer__service__install_local and node__service__install_local in sequence, then runs bin/console cache:clear inside the container.

src/wexample_wex_addon_dev_php/services/symfony/commands/service/deploy.py is the post-deployment hook: it runs doctrine:migrations:migrate --no-interaction --allow-no-migration inside the container. --no-interaction is required because the deploy webhook has no TTY; without it, data-loss prompts silently abort the migration.

WordPress

src/wexample_wex_addon_dev_php/services/wordpress/commands/url/replace.py resolves the current site URL by running wp option get siteurl inside the wordpress_cli sidecar, then calls wp search-replace <old> <new> --skip-columns=guid. When --new-url is omitted, the target URL is guessed from the first domain in the runtime config's app.domains list.

Call path

A typical Python service command goes through these steps:

1. The wex CLI resolves the command name (e.g. symfony/service/install_local) through the registry built by PhpAddonManager.get_package_module, which points at the wexample_wex_addon_dev_php package for auto-discovery.
2. The framework constructs an ExecutionContext carrying the kernel, IO handle, and the resolved AppService for the target service.
3. The command function receives context and service; it calls service.addon_manager.docker_exec(service.name, [...]) to run a shell fragment inside the named Docker container (e.g. {app_project_name}_symfony).
4. For commands that delegate to the generic Composer routines (Laravel install_local and refresh_lock, Symfony install_local), the inner function is called directly in the same Python frame — composer__service__install_local.function(context=context, service=service) — reusing the same service so execution happens inside the calling service's container, not the composer container.
5. YAML commands (maintenance/enable.yml, db/migrate.yml) follow the same resolution path but their shell scripts are executed by the wex YAML runner, which maps runner: docker + service: laravel to the equivalent docker exec call.

Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the Wexample Suite documentation for the complete package ecosystem.

Dependencies

• attrs: >=23.1.0
• cattrs: >=23.1.0
• wexample-filestate-php: >=6.5.0
• wexample-filestate-symfony: >=2.1.0
• wexample-wex-addon-ai: >=18.1.0
• wexample-wex-addon-app: >=33.0.0
• wexample-wex-addon-dev-javascript: >=8.3.0

Versioning & Compatibility Policy

Wexample packages follow Semantic Versioning (SemVer):

• MAJOR: Breaking changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Free to use in both personal and commercial projects.

About us

Wexample stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the project roadmap for upcoming features and improvements.

Status & Compatibility

Maturity: Production-ready

Python Support: >=3.10

OS Support: Linux, macOS, Windows

Status: Actively maintained

Useful Links

• Homepage: https://github.com/wexample/python-wex-addon-dev-php
• Documentation: docs.wexample.com
• Issue Tracker: https://github.com/wexample/python-wex-addon-dev-php/issues
• Discussions: https://github.com/wexample/python-wex-addon-dev-php/discussions
• PyPI: pypi.org/project/wexample-wex-addon-dev-php

Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.