An update on the starting guide

[a-barbieri]

I was following the first option of the starting guide:

For new projects you can just copy all files from plugin/ and rename the "example" strings.

Being new to writing Wordpress plugin I had to gather some information which weren't specified in the guide. Also I had to make some research to clarify some implicit actions required but not written in the guide.

Specifically:

1. Each file inside the src folder should be called after the class it contains.
2. Inside the root file (by default is plugin.php) you should reference the class which initialise your plugin.
3. The EXAMPLE constant is there just as an example (yes, example again ¯_(ツ)_/¯).
4. DO NOT USE a hyphen in WPTT_DB_NAME.
5. The autoload setting in composer.json.
6. Tests written this way require php 7.
7. Shall I change plugin.php along with my plugin's name?
8. What do you do once you copy/paste/update everything? You install dev dependencies.
9. What do you do once you installed dev dependencies? You install Wordpress.

---

1. Each file inside the src folder should be called after the class it contains.

You define a mapping from namespaces to directories. The src directory would be in your project root, on the same level as vendor directory is. An example filename would be src/Foo.php containing an \Acme\Foo class. NOTE: we are imaging your plugin name is Acme.

Reference: https://getcomposer.org/doc/01-basic-usage.md#autoloading

2. Inside the root file (by default is plugin.php) you should reference the class which initialise your plugin

I just want to point out that \Example\Example is a bit misleading. See below:

wp-testing-tools/plugin/plugin.php

Line 19 in 96e444b

if (!\class_exists('\Example\Example')) {

wp-testing-tools/plugin/plugin.php

Line 32 in 96e444b

\Example\Example::init();

The first Example refer to the namespace of the plugin, whereas the second Example refers to the class responsible for initialising the plugin.

In a real case scenario the \Example\Example you see here above should become \Acme\Loader, considering your plugin is called Acme and the class that inisialises it is named \Acme\Loader.

The other important thing is that the \Acme\Loader declaration should reside in src/Loader.php file.

Obviously Loader is just one option: it can be whatever you want.

3. The EXAMPLE constant is there just as an example (yes, example again ¯_(ツ)_/¯).

What you see here below:

wp-testing-tools/plugin/src/Example.php

Line 7 in 96e444b

define( 'EXAMPLE', 'initialized' );

is only used to make an initial test:

wp-testing-tools/plugin/tests/wpunit/ExampleTest.php

Line 28 in 96e444b

$this->assertEquals(EXAMPLE, 'initialized');

There is no real use other than that. (is there?!)

4. DO NOT USE a hyphen in WPTT_DB_NAME

I'm referring to this line:

https://github.com/valu-digital/wp-testing-tools/blob/master/plugin/.env.docker#L7

If your plugin is called My Beautiful Plugin your WPTT_DB_NAME in the .env.docker file should be my_beautiful_plugin.

DO NOT USE HYPHEN: you cannot name it my-beautiful-plugin.

5. The autoload setting in composer.json

wp-testing-tools/plugin/composer.json

Line 19 in 8625ae7

"Example\\": "src/"

Considering a plugin named Acme then this line should be "Acme\\": "src/". But if your plugin as multiple namespace levels like \My\Beautiful\Plugin, then this should be My\\Beautiful\\Plugin\\": "src/".

6. Tests written this way require php 7

wp-testing-tools/plugin/tests/wpunit/ExampleTest.php

Line 10 in 8625ae7

public function setUp(): void

This line works only on php 7+.
That's not a big deal as PHPUnit 9.1.4 requires PHP 7.3+ already.

## 7. Shall I change plugin.php along with my plugin's name?

I guess so. Clearly not! Keep plugin.php.

8. What do you do once you copy/paste/update everything? You install dev dependencies.

To install Composer dev dependencies.

composer install

⚠️ NOTE: In case you are like me and you don't have/don't want to install PHP on your machine but use Docker instead, refer to this thread which shows how to do it.

9. What do you do once you installed dev dependencies? You install Wordpress

composer wp-install

⚠️ NOTE: In case you want to use Docker you run the following command instead:

./docker/run compose

⚠️ NOTE: at the time of this writing the Dockerfile wasn't working. I made a PR that fixes it.

[noknokcody]

Thanks for this, it was a huge help!

Also worth mentioning I had a bunch of issues with minimum PHP versions of libraries. Adding this to my composer.json ensured libraries were compatible with the 7.2 (used by the docker project).

    "config": {
        "platform": {
            "php": "7.2.24"
        },
        "optimize-autoloader": true
    }