DEV Community: Lucas Carvalho

The PHP Orkestra Framework

Lucas Carvalho — Mon, 06 May 2024 02:05:53 +0000

Introduction

Some months ago I started a side project aiming for study and personal use to create a new PHP framework capable to seamless integrate with wordpress as a plugin or to work fully autonomous. Based on PSR and best practicess, following SOLID and DRY principles at the best.

This last week I finaly ended the first version of the Orkestra framework core, with all critical components tested and working as expected.

As Matt Mullenweg said before, "code is poetry" and the Orkestra framework whas build to allow developers to create art expressed in if's and classes, leveraging the best in PHP ecossistem to allow you to conduct each small part of your software to work seamsly with other with nice and elegant structure.

The goal of Orkestra is to be high extensible, simple to work with and integrate with different environments as Wordpress (the reason that this first release does not includes a database ORM).

Why not just use Laravel?

Currently Laravel is the "go to" for new PHP applications to mostly developers today, if not, plain PHP, Slim, Symfony and other frameworks does the job, but for Wordpress, custom PHP boilerplates or/and outdated PHP patterns (aka, single ton) is what we have for work in mostly cases, if not, hacky ways to integrate frameworks as Laravel itself or parts of it to leverage a better code structure.

Orkestra itself does not contain WordPress connections, this part will be released soon with Orkestra WP, a package that will contain a proxy structure to easily convert a Orkestra application into a WordPress plugin just by changing the service providers.

So this framework is not builded to "replace" Laravel and other great options but to be a well structured, fast and light option to build well designed software for situations were a more lightweight and tailored solution is needed to fast develop. While Laravel and other frameworks offer robust features and extensive toolsets, they may be overkill for certain projects or keep their extensibility sourounded by their only ecosystem.

So how to start a new project?

To easily start a new project, we also have a skeleton that will initiate the codebase with just a few question and that will be incremented with time adding more templates as "react", "wordpress" and options containing datatbase ORM and user repositories which will allow you to easily launch more complex PHP applications in a standard way.

So to start you only need PHP 8.2+ and composer installed, then run:

composer create-project luccpl/orkestra-skeleton {project_name}

Change {project_name} to your project name, then you just need to answer the questions to create your application.

After this you will end up with the following codebase inside the created directory:

As you can see this template will add and configura the Pest test suite with a custom TestCase class that will start the application for your tests, making easy to test your application services (as used by Orkestra itself) and you will see a basic application, with a single route in the file config/routes.php that calls a Controller that simply render a Twig view.

Now you can go to the root directory in a terminal and run our CLI application to start the server on port :3000.

php maestro app:serve

With this ready you can start building your application by following the documentation.

I recommend you to also follow a repository pattern in your application, to keep best principles and your application easy to mantain and use our Orkestra\Entities\AbstractEntity and the Orkestra\Entities\EntityFactory.

Conclusion

Orkestra presents a fresh approach to PHP development, offering a seamless integration with WordPress on the horizon. While not aiming to replace established frameworks like Laravel, it provides a lightweight, extensible solution for projects where a tailored, efficient codebase is preferred.

Starting a new project is made simple with the Orkestra skeleton, initiating you with a clean structure and options for further customization.

Thanks for reading and see you in next updates.

XDebug with WP-Setup

Lucas Carvalho — Wed, 24 Apr 2024 23:11:16 +0000

Introduction

WP Setup has been updated to version 1.1.0, introducing Xdebug support and allowing for easy generation of test coverage reports.

Additionally, some small fixes and improvements were made, such as using the adm-zip library instead of unzipper, providing a simpler and reliable extractor that avoids uncompress errors as with Query Monitor (that we add by default in wp-setup.json during the initialization process) that in some cases did not complete the unzip process correctly, causing errors during WordPress loading.

Running XDebug

Now we can simple start the containers with XDebug running by adding a --xdebug flag in the start command. This will restart all server and CLI containers with the xdebug up and running.

You can use the recommended scripts in wp-setup readme to easily start with the command npm run env:start:xdebug.

With this, you can use XDebug in all environments, enabling debugging of CLI commands, tests (facilitating a better TDD approach in development), and normal HTTP executions through the server.

To only stop the XDebug when not needed, you can run the stop command with the flag --xdebug or with our package scripts run npm run env:stop:xdebug.

Mapping directories

As we are running inside docker containers, we need to map our local directories with the container ones so we can fully use the debugger with our IDE.

In VSCode for example this can be easily done by adding the following .vscode/launch.json file:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html/wp-content/plugins/my-plugin": "${workspaceFolder}/plugins/my-plugin",
            }
        }
    ]
}

Replace the pathMappings with your project directories accordingly

With this we can go to VSCode debug tab and click in "Listen for XDebug".

Tests coverage repport

An important aspect of any development project is to measure how much of our code is tested. This allows us to gauge the reliability of our codebase before sending it to production.

The CLI test container now starts with XDebug in "coverage" mode by default, enabling the generation of this report.

Currently, it is not possible to run --coverage directly with our global-pest command, to use the cli coverage (very usefull to enforce a minimal test coverage in CI processes) you need to require pest and yoast/phpunit-polyfills locally in your project.

composer require --dev pestphp/pest yoast/phpunit-polyfills

then you can run your tests with your locally installed pest with:

npx wp-setup run -w . wp-test-cli ./vendor/bin/pest

This will give you full pest CLI access and allow the use of --coverage flag.

Conclusion

This latest update, introduces important enhancements, which are designed to streamline and enhance your WordPress development experience. While the new features enhance the local development process by introducing powerful debugging and testing capabilities, it is important to note that the WP Setup is not yet fully optimized for running CI processes directly. However, the groundwork has been laid, paving the way for future enhancements that will support more robust CI integrations.

As the sole developer behind WP Setup, I invite other developers to explore the potential of this tool. Your feedback and contributions are invaluable to not only improve its existing features but also to help in expanding its capabilities. The project is open for contributions on GitHub, and I am eager to collaborate with other developers to make WP Setup even more powerful and versatile.

Please take this opportunity to test WP Setup. Together, we can work towards making a comprehensive development tool that better serves the WordPress community.

Wordpress tests with Pest and WP Setup

Lucas Carvalho — Wed, 17 Apr 2024 23:55:34 +0000

Introduction

In my last post here, I presented my new WordPress environment tool called WP Setup, and at that moment it was missing a test environment.

Today, I finished the first implementation of this environment, adding Pest and PHPUnit in v10.5, which is currently not supported by default with WP Env.

So, let's put our hands a little bit into the code and see how to start doing tests with WP Setup and Pest in a few steps creating a basic plugin.

The plugin basis

To build this simple example, create a directory called my-plugin with just a my-plugin.php file containing the WP header requirements.

Then, start an npm project in this directory by typing npm init -y in a terminal.

Now we just need to add WP Setup as a development package by typing the following command in the terminal:

npm install wp-setup --save-dev

And in the scripts section of the created package.json file, add the json bellow:

"scripts": {
    "wp-setup": "wp-setup",
    "env:start": "wp-setup start",
    "env:stop": "wp-setup stop",
    "env:destroy": "wp-setup destroy",
    "env:run": "wp-setup run",
    "env:wp": "wp-setup wp",
    "env:help": "wp-setup help",
    "env:composer": "wp-setup run wp-cli --workdir . composer",
    "env:pest": "wp-setup run wp-test-cli --workdir . global-pest"
}

The init command

In this last update, the init command was added, and with this, it's now only two commands to set up the environment.

Create the wp-setup.json file:

npm run wp-setup init

Create the test configuration:

npm run wp-setup -- --tests

After this, you will end up with this structure:

Starting the environment

Now, we are fully set up and just need to start the environment.

Please, be sure to have the ports :80 and :443 available on your machine and Docker started.

Run:

npm run env:start

After a while, you can visit your environment at https://my-plugin.localhost.

Finally running the tests

Now that all is up and running, we can start our tests with Pest by running:

npm run env:pest

As you can see, the example tests ran as expected, and you can create new tests following the Pest documentation and the WordPress Tests Handbook.

Stopping the environment

Now that we've finished our work here, we can stop our environment, removing the existing Docker containers and freeing the used ports. The images and development volumes will persist on your machine, making it fast to start again.

npm run env:stop

Also, if you prefer, you can destroy the entire environment by running:

npm run env:destroy

Conclusion

I hope this simple tutorial helps you effectively utilize WP Setup with Pest for your WordPress development projects.

If you have any questions or need further assistance, please feel free to comment out here. Happy coding!!!

Introducing WP Setup

Lucas Carvalho — Sat, 13 Apr 2024 23:38:17 +0000

Introduction

Developing WordPress plugins and themes often requires a reliable development environment. Current we have good solutions as wp-env from Autommatic, Local WP from WP Engine, Docker, XAMPP (for old ones) and so on. All this can be good suits for a development environment, specially Local WP that is probably the easiest one to get up and running and wp-env that leverages Docker as a development environment in a very easy way to use.

After use most of existing options and find some barriers in specific cases, I decided to create my own solution, leveraging Docker as wp-env but allowing more flexibility and customization for advanced use cases.

Why a new tool?

Until some months ago I was using Local WP as my go-to solution in most of my projects and in a specific and more advanced one, Docker with Docker Compose to create a custom environment. Recently I started to use wp-env and I was very impressed with the simplicity and power of this tool, also to easily configure a test environment with PHPUnit by default, but again, in a specific use case I found a limitation that makes me get back to Docker and Docker Compose and lost some time to configure my environment as I need.

In this last and specific case I was working with a Laravel application that needs to interact with a WordPress site, and as both works from different Compose projects, I need to add a custom configuration to allow internal requests between them, what get easy to do with Laravel Sail, simply adding a extra_hosts configuration to the docker-compose.yml file but was impossible to do with wp-env and probably will not be implemented as we can see from this Github issue.

So, I decided to create my own solution, leveraging a similar approach to wp-env but allowing more flexibility and customization, also removing some custom scripts that I need to further customize my environment (as configuring WordPRess Multisite).

Meet WP Setup

WP Setup is a simple and powerful tool to create a WordPress development environment using Docker and Docker Compose, providing a simple CLI tool that allows you to create a new WordPress project in a few seconds.

Currently it should be used as a node development dependency and can be easily installed using npm, pnpm or yarn.

Features

Currently these are the main available features of WP Setup:

Create a new WordPress environment in a few seconds
Customize your environment using a simple configuration file or CLI options
Allow inject custom Docker Compose file to override the default one, allowing you to customize your environment as you need (add custom services, volumes, networks, etc)
Easily configure Wordpress Multisite with subdomains or subdirectories
Uses the new FrankenPHP server to add SSL support to your local environment

Under development

The Test environment with PHPUnit and Pest is ready and you can see here how to start using

This is a new tool and is under development. These way some features are not implemented yet, as:

Test environment with PHPUnit
Build environment to easily build your project for production
Xdebug support
Composer CLI to easily run composer commands in your WordPress project without the need to enter in the container or even have PHP installed in your machine
Sync Hosts to automatically add your development domain to your hosts file

My priority at this moment is to implement the test environment with PHPUnit and Xdebug support, as I need this in my daily work, but I'm open to suggestions and contributions.

Also I'm looking into the possibility to use WordPress JS Hooks to allow further customization of the environment (aka adding environment plugins). This can be useful to standardize the creation and configuration of different services and tools in the environment, such as MailHog, Redis, etc.

Give it a try

I invite you to give WP Setup a try for your WordPress development projects. Whether you're a novice or an advanced user, WP Setup aims to simplify your workflow while offering the flexibility you need.

For detailed installation instructions and to start using WP Setup, visit this link. Your feedback and contributions will help to improve and expand the capabilities of WP Setup. Let's make WordPress development smoother and more efficient together!