Download the PHP package wp-oop/plugin-boilerplate without Composer

On this page you can find all versions of the php package wp-oop/plugin-boilerplate. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package plugin-boilerplate

WP-OOP - Plugin Boilerplate

Continuous Integration

A boilerplate for starting WordPress plugins quickly.

Details

Use this project as a starter for your modular WordPress plugin!

Features

Usage

Getting Started

  1. Use this template

    This GitHub repository is a template. Use it to create a project of your own from.

    Of course, you can always clone and push it elsewhere manually, or use another method of forking, if more appropriate.

  2. Customize project

    Note: Asterisk * below denotes that changing this value requires rebuild of the images in order to have effect on the dev environment.

    • Copy .env.example to .env.
    • .env:

      • PLUGIN_NAME - The slug of your plugin. Must correspond to the name of the plugin folder.
      • BASE_PATH - If you are using Docker Machine, i.e. on any non-Linux system, set this to the absolute path to the project folder inside the machine. If you are on Linux, you do not need to change this.
      • PROJECT_MOUNT_PATH - The path to mount the project folder into. This should be the absolute path to the folder of your plugin inside the container.
      • PROJECT_NAME - Slug of your project. Used mainly for naming containers with container_name. This is helpful to run multiple projects on the same machine.
      • PHP_BUILD_VERSION - The version of PHP, on which the plugin will be built. This should correspond to the minimal PHP requirement of your plugin. Used to determine the tag of the php image.
      • PHP_TEST_VERSION* - The version of PHP, on which the plugin will be run. This should correspond to the maximal PHP requirement of your plugin. Used to determine the tag of the wordpress image.
      • WORDPRESS_VERSION* - The version of WordPress, on which the plugin will be run. Used to determine the tag of the wordpress image.
      • DB_USER_PASSWORD - This and other `DB_` variables are used to determine the password to the WordPress database. Change these if you want to secure your deployed application.
      • WP_DOMAIN* - The domain name of the WordPress application, which contains your plugin. Among other things, used to set up the local dev image. Corresponds to the alias used in the hosts file, if local. This value is also used in the PHPStorm's DB integration. If this value is changed, PHPStorm's configuration must be updated.
      • WP_TITLE* - The title of the WordPress application, which contains your plugin. No quotes, because Docker does not expand variables in this file. It is used during automatic installation of WordPress inside the local dev image. This value is also used in the PHPStorm's DB integration. If this value is changed, PHPStorm's configuration must be updated.
      • ADMIN_USER - This and other `ADMIN_` variables are used to determine WordPress admin details during automatic WordPress installation with WP-CLI.
    • composer.json:

      • name - Name of your package.
      • description - Description of your package.
      • authors - You and/or your company details.
      • require - Your project's package and platform requirements. You may want to change the PHP version if your minimal requirement is different. Don't forget to update PHP_BUILD_VERSION in .env.
      • require-dev - Your project's development requirements. You may want to add plugins here to get related IDE features; see Adding Plugins for more information on this subject.
    • Module composer.json: This bootstrap uses the awesome composer-merge-plugin to keep module dependencies together with modules. This allows keeping track of which dependencies belong to which modules, detect dependency incompatibilities, and moving modules out of the package into packages of their own when necessary.

      Modules can be installed from other packages, or included in the package. In the latter case, they should be added to the directory modules. One such module, the demo module of the plugin, is already included in the package. This is there only for demonstration purposes, and can be renamed and re-written, or entirely removed. Either way, see Adding Modules for more information on how to configure which modules the application will use.

      Important: Adding modules to other modules as dependencies is considered bad practice. Modules don't interact with each other directly, but use an approach similar to DDD but applied to service definitions to ensure that they are as isolated as possible. Instead, have the app (project's main package) depend on other modules, and wire them together in the app's main module. One legit reason for a module to depend on another module is if that other module isn't necessarily loaded as a module, but its symbols are needed somewhere. However, in this case it's important to avoid thinking of it as a module until it is added as the app's dependency, and to think of it as simply a library.

  3. Build everything

    1. Build the environment.

      In order to develop, build, and test the plugin, certain things are required first. These include: the database, WordPress core, PHP, Composer, and web server. The project ships with all of this pre-configured, and the Docker services must first be built:

    2. Build the plugin in place.

      In order for the project source files to have the desired effect, they first must be built into their runtime version. This may include: installing dependencies, transpilation, copying or archiving files, whatever the modules require to have desired effect, etc. At the same time, a single entrypoint to various tasks performed as part of the project build or QA allows for more centralized and automated control over the project.

      For this reason, the Makefile is shipped with the project, declaring commands for commonly run tasks, including build. Run the following command to build the plugin, including modules, in the plugin source directory: this makes it possible to preview and test changes instantly after they are made.

      Note: This step includes installation of declared dependencies. See Updating Dependencies for more info on this subject.

  4. Spin up the dev environment

    Run the following command in the terminal. If you use Docker Machine, you will need to start it and configure your environment first with docker-machine start and docker-machine env.

    This will bring up only the dev environment and its dependencies, which right now is the database. The database is a separate service, because in a deployed environment you may choose to use a different DB server.

    After this, add an entry to your local hosts file. The host should correspond to the value of WP_DOMAIN from the .env file. The IP would be Docker machine's IP address. On Linux, this is the same as your machine's IP address on the local network, and usually 127.0.0.1 (localhost) works. If you are using Docker Machine (in a non-Linux environment), use docker-machine ip to find it.

    Now you should be able to visit that domain, and see the website. The admin username and password are both admin by default, and are determined by the ADMIN_USER and ADMIN_PASS variables from the .env file. Your plugin should already be installed and active, and no other plugins should be installed. If this is not the case, inspect the output you got from docker compose up.

    If you use PHPStorm integrations that involve Docker, such as Composer, you maybe receive the error "Docker account not found". This is because, for some reason, PHPStorm requires the same name of the Docker deployment configuration to be used in all projects, and there currently does not seem to be a way to commit that to the VCS. Because of this, you are required to create a Docker deployment yourself. Simply go to Project Settings > Docker and create a configuration named precisely "Docker Machine".

  5. Release

    When you would like to release the current working directory as an installable plugin archive, the shipped build script needs to perform a few transformations (like optimize prod dependencies), and archive the package in a specific way. The following command will result in an archive with name similar to plugin-0.1.1-beta21+2023-08-12-12-37-22_105188ec9180.zip being added to build/release:

    As you can see, the resulting archive's name will reflect the time and commit hash as SemVer metadata, aside from the version itself. If RELEASE_VERSION is omitted, dev is used by default to indicate that this is not a tagged milestone, but work in progress.

    Note: If the current working directory contains any edits registerable by Git (disregarding any .gitignore rules), the commit hash will reflect a point in history of the files in build/dist, rather than of project history. To ensure that a concrete version is being released, clean the directory tree entirely. The best way to do that is probably to create a fresh clone.

Updating Dependencies

Composer is installed into the build service's image. To run composer commands, use docker compose run. For example, to update dependencies you can run the following:

If you use PHPStorm, you can use the composer integration, as the project is already configured for this.

Note: If PHPStorm does not automatically assign a PHP interpreter for Composer, set it to use the "Build" interpreter. All build tasks, including dep installation, must be run inside the build service, which corresponds to that interpreter.

Do not run composer update for the modules' composer.json file! All Composer operations must be performed on the root package's composer.json file.

Any changes to the project folder are immediately reflected in the dev environment, and this includes the vendor folder and composer.lock file. This is because the project's folder is mounted into the correct place in the WordPress container.

Adding Modules

This boilerplate promotes modularity, and supports Dhii modules out of the box. Any such module that exposes a ModuleInterface implementation can be loaded, allowing it to run in the application, and making its services available.

The list of modules returned by src/modules.php is the authoritative source of modules in the application. Because it is PHP code, modules can be loaded in any required way, including:

External Modules

To add a module from another package, require that package with Composer and add the ModuleInterface instance to the list.

Local Modules

To add a local module, add the module to the modules folder, and do the same as for any other module. Local modules may also declare their own dependencies by adding a composer.json file to their root folder. These files will be picked up by Composer when updating dependencies in the project root, thanks to the composer-merge-plugin, provided that composer update --lock is run before composer update. This is a great way to separate module dependencies from other dependencies. Consult that Composer plugin's documentation for more information.

Adding Plugins

If your plugin depends on or can integrate with other plugins, you may want to add them to the environment. In order to get IDE features such as auto-suggest for other plugin code, you may want to add them to your require-dev.

In order to have the test WordPress website to have another plugin installed and active, add an appropriate WP-CLI command to the docker/wp-entrypoint.sh script. Example:

Please note:

QA

Run all QA tools at once by using the qa target in the included Makefile. All QA is done in the test service.

Testing Code

Run all tests at once using the test target:

Static Analysis

Run all static analysis tools at once by using the scan target:

Debugging

The bootstrap includes xDebug in the test service of the Docker environment, and PHPStorm configuration. To use it, right click on any test or folder within the tests directory, and choose "Debug". This will run the tests with xDebug enabled. If you receive the error about xdebug.remote_host being set incorrectly and suggesting to fix the error, fix it by setting that variable to your machine's IP address on the local network in the window that pops up. After this, breakpoints in any code reachable by PHPUnit tests, including the code of tests themselves, will cause execution to pause, allowing inspection of code.

If you change the PHP version of the test service, the debugger will stop working. This is because different PHP versions use different versions of xDebug, and because the path to the xDebug extension depends on its version, that path will also change, invalidating the currently configured path. To fix this, the "Debugger extension" fields in the interpreter settings screen needs to be updated. You can run docker compose run test ls -lah /usr/local/lib/php/extensions to see the list of extensions. One of them should say something like no-debug-non-zts-20170718. Change the corresponding part of the "Debugger extension" path value to that string.

At this time, inspection of code that runs during a web request is not available.

Database UI

This bootstrap comes ready with configuration for PHPStorm's database integration. To use it, its settings must be up to date with the value of DB_USER_PASSWORD. Using it is highly recommended, as it is an integrated DB client, and will provide assistance during coding.

Alternatively, you are welcome to install and configure a phpMyAdmin service or similar.


All versions of plugin-boilerplate with dependencies

PHP Build Version
Package Version
Requires php Version ^7.2 | ^8.0
dhii/module-interface Version ^0.3-alpha1
psr/container Version ^1.0
dhii/versions Version ^0.1.0-alpha2
dhii/containers Version ^0.1.4-alpha2
dhii/services Version ^0.1.1-alpha3
wp-oop/wordpress-interface Version ^0.1.0-alpha1
wikimedia/composer-merge-plugin Version ^2.0.1
symfony/polyfill-php80 Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package wp-oop/plugin-boilerplate contains the following files

Loading the files please wait ....