Download the PHP package tbessenreither/copycat without Composer

PHP Copycat

What is it?

PHP Copycat is a Composer package that provides a simple and safe way for PHP packages to automate file copying and configuration modifications in the projects that depend on them. It allows package authors to define a CopycatConfig class with operations like copying files, modifying JSON configurations, adding entries to .gitignore, and registering Symfony bundles. These operations are executed automatically when users run composer install or composer update, ensuring that necessary setup steps are performed without manual intervention.

All operations are designed to be safe and are based on a whitelist of allowed namespaces, so the project needs to explicitly allow the package to perform operations. Additionally, Copycat includes smart system validation to ensure that operations are only executed if the project matches the expected system (e.g., only copying Symfony files if the project is a Symfony app). This prevents accidental or unsafe changes in the wrong type of project.

Config files like the composer.json have additional protections to prevent malicious or accidental changes. For example, writes outside of the extra section are not allowed via json modifier, and the copy operation will not allow copying files from outside your package scope, ensuring safe and predictable automation. Additional to that all targets are predefined via enums in copycat, so there is no possibility to write to arbitrary paths in the project. This makes it a secure and reliable tool for package authors to enhance the user experience of their packages with necessary setup steps.

Features

Current features

• Copy files to specific targets (e.g., DDEV commands, Symfony, public, etc.)
• Add or modify JSON values at any path in a target file
• Add entries to your project's .gitignore in a grouped, idempotent way
• Add entries to your project's .dockerignore in a grouped, idempotent way (only in projects with a Dockerfile)
• Register Symfony bundles automatically in config/bundles.php
• Smart system validation: Only runs operations if your project matches the expected system for the target (e.g., Symfony, DDEV)
• Secure: prevents copying files from outside your package scope
• Easily integrate with Composer scripts for automation
• Partial reversal of operations on package removal (removing copied files, removing bundle, removing .gitignore section)
• Adding values to .env files. All variables will be grouped by package namespace, and you can choose to overwrite existing entries or keep them to prevent accidental overwrites of user values.

Planned Features

PHP Copycat is actively developed. Planned features include:

• Echo of messages after execution (e.g., "Package [Packagename]: To use this package, do X, Y, Z...")

Operation support matrix

Legend: ✅ supported, 🔨 working on it, 🔴 not supported

Setup

Require Copycat as a dependency via composer.

While you don't technically need copycat as a dependency in your package it is recommendet to at least use it as a dev dependency so you can take advantage of autocompletion and prevent errors.

Within a package

Create a CopycatConfig class in the autoload root of your package that implements CopycatConfigInterface. This class will define the operations to be performed in the projects that depend on your package (e.g., copying files, modifying JSON, adding .gitignore entries, registering Symfony bundles). See the Available Operations section below for details and examples.

Example:

Within a project

To execute Copycat operations in a project, add the following to your composer.json scripts section:

On first execution Copycat will add a boilerplate Whitelist to your composer.json if it doesn't exist, which you can then customize to allow specific packages to perform operations in your project. This ensures that no package can perform operations without your explicit permission.

The section will look something like this after the first execution:

This is it. Whenever you run composer install, composer update, or composer remove, Copycat will automatically execute the defined operations in the CopycatConfig classes of your dependencies, performing necessary setup steps in a safe and system-aware manner.

Example output on execution:

Copycat now supports partial reversal of operations on package removal.

Available Operations

Table of operations

• copy
• copyDirectory
• jsonAdd
• gitIgnoreAdd
• dockerIgnoreAdd
• symfonyBundleAdd
• symfonyAddServiceToYaml
• envAdd

copy

Copy a file from your package to a specific target in the project (e.g., DDEV commands, Symfony config, public directory, etc.). The operation will only be executed if the project matches the expected system for the target (e.g., only copying Symfony files if the project is a Symfony app). This ensures that files are only copied in relevant projects, preventing accidental changes in the wrong type of project.

Available targets

• CopyTargetEnum::PROJECT_ROOT - copies to the root directory of the repository.
• CopyTargetEnum::DDEV_COMMANDS_WEB - copies to the .ddev/commands/web directory of the project. Only runs if the project is a DDEV project.
• CopyTargetEnum::DDEV_COMMANDS_HOST - copies to the .ddev/commands/host directory of the project. Only runs if the project is a DDEV project.
• CopyTargetEnum::PHPSTORM_EDITOR_IDEA - copies to the .idea directory.
• CopyTargetEnum::PHPSTORM_RUN_CONFIG - copies to the .run directory.
• CopyTargetEnum::SYMFONY_BIN - copies to the bin directory of the project. Only runs if the project is a Symfony app.
• CopyTargetEnum::SYMFONY_CONFIG_PACKAGES - copies to the config/packages directory of the project. Only runs if the project is a Symfony app.
• CopyTargetEnum::SYMFONY_CONFIG_ROUTES - copies to the config/routes directory of the project. Only runs if the project is a Symfony app.
• CopyTargetEnum::PUBLIC - copies to the public directory of the project.
• CopyTargetEnum::COPYCAT_CONFIG - copies files to the .copycat directory in the project root.
• CopyTargetEnum::GIT_HOOKS - copies files to the .git/hooks directory in the project root.
• CopyTargetEnum::CLAUDE - copies files or folders to the .claude directory.

copyDirectory

Copies a whole directory to a given target. On removal only files present in the package will be removed from the project. Empty directories will be removed.

jsonAdd

Add or modify JSON values at any path in a target JSON file. The operation will only be executed if the project matches the expected system for the target (e.g., only modifying Symfony config if the project is a Symfony app). This ensures that configuration changes are only made in relevant projects, preventing accidental changes in the wrong type of project.

Available targets

• JsonTargetEnum::COMPOSER_JSON - modifies the composer.json file of the project. Only allows modifications in the extra section to ensure safe changes.

gitIgnoreAdd

Add entries to the project's .gitignore file grouped by package namespace so you see what packages are adding which entries. The operation will only be executed if the project is a git repository.

dockerIgnoreAdd

Add entries to the project's .dockerignore file grouped by package namespace, exactly like gitIgnoreAdd. The operation will only be executed if the project contains a Dockerfile, and the file is created if it does not exist yet.

Because the entries live in their own ###> namespace group, a project keeps its own patterns — use this instead of copying a whole .dockerignore over the project's file.

symfonyBundleAdd

Register a Symfony bundle automatically in config/bundles.php. The operation will only be executed if the project is a Symfony app. This methods checks the given class for implementing the Symfony BundleInterface to prevent invalid entries in bundles.php. If the class does not implement the interface or other problems, the method will refuse to add the bundle and print the error in the console output.

symfonyAddServiceToYaml

Register a Symfony service automatically in config/services.yaml. The operation will only be executed if the project is a Symfony app. This methods checks if the service is already registered to prevent duplicate entries in services.yaml. If the service is already registered or other problems occur, the method will refuse to add the service and print the error in the console output.

envAdd

Add values to .env files. Keys will be sorted into the group that writes it, even if they are already part of the target file. This ensures that it's always clear which package is responsible for which entries in the .env file. You can choos to overwrite existing entries by setting the overwrite flag to true, this is helpfull for managing entries in the .env.example file where you want to make sure that the entries are always up to date, but for the regular .env file it's recommended to keep overwrite set to false to prevent accidental overwrites of user values.

You also can use the EnvVar class for a more defined way of adding env vars.

This will add the following entries:

Available targets

All files will be created if they don't exist. There is no system check for this operation, as .env files are used in various types of projects, so it's up to you to make sure that you are adding entries to the right file for your project type and use case.

• EnvTargetEnum::DOT_ENV - modifies the .env file. !BE CAREFULL WITH THE OVERWRITE FLAG HERE!
• EnvTargetEnum::DOT_DEV - modifies the .env.dev file.
• EnvTargetEnum::DOT_EXAMPLE - modifies the .env.example file.
• EnvTargetEnum::DOT_LOCAL - modifies the .env.local file.
• EnvTargetEnum::DOT_TEST - modifies the .env.test file.

License

MIT