Skip to content

Commit cb5924c

Browse files
XedinUnknownXedinUnknown
committed
Add readme
1 parent 00e1890 commit cb5924c

File tree

1 file changed

+137
-0
lines changed

1 file changed

+137
-0
lines changed

‎README.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# WP-OOP - Plugin
2+
A skeleton for starting WordPress plugins quickly.
3+
4+
## Details
5+
Use this project as a starter for your modular WordPress plugin!
6+
7+
### Feaures
8+
- **Docker** - Develop and test your plugin with Docker. Use an environment
9+
tailored for your plugin. See changes instantly in the browser. Build
10+
a Docker image containing a complete WordPress installation with your
11+
plugin and all pre-requisites.
12+
13+
### Usage
14+
15+
#### Getting Started
16+
Use Composer to bootstrap your project.
17+
18+
1. Clone and install deps:
19+
20+
```bash
21+
composer create-project wp-oop/plugin my_plugin
22+
```
23+
24+
Here, `my_plugin` is the name of the project folder. Should correspond
25+
to the slug of your plugin.
26+
27+
2. Customize project
28+
29+
_Note_: Asterisk `*` below denotes that changing this value requires rebuild of the images in order
30+
to have effect on the dev environment.
31+
32+
- Copy `.env.example` to `.env`.
33+
- `.env`:
34+
* `PLUGIN_NAME` - The slug of your plugin. Must correspond to the name of the plugin folder.
35+
* `BASE_PATH` - If you are using [Docker Machine][], i.e. on any non-Linux system, set this
36+
to the absolute path to the project folder _inside the machine_. If you are on Linux,
37+
you do not need to change this.
38+
* `PROJECT_MOUNT_PATH` - The path to mount the project folder into. This should be the absolute
39+
path to the folder of your plugin inside the container.
40+
* `PROJECT_NAME` - Slug of your project. Used mainly for naming containers with [`container_name`][].
41+
This is helpful to run multiple projects on the same machine.
42+
* `PHP_BUILD_VERSION` - The version of PHP, on which the plugin will be _built_. This should
43+
correspond to the minimal PHP requirement of your plugin. Used to determine the tag of
44+
the [`php`][] image.
45+
* `PHP_TEST_VERSION`* - The version of PHP, on which the plugin will be _run_. This should
46+
correspond to the maximal PHP requirement of your plugin. Used to determine the tag of
47+
the [`wordpress`][] image.
48+
* `DB_USER_PASSWORD`* - This and other `DB_*` variables are used to determine the password
49+
to the WordPress database. Change these if you want to secure your deployed application.
50+
* `WP_DOMAIN`* - The domain name of the WordPress application, which contains your plugin.
51+
Among other things, used to set up the local dev image. Corresponds to the alias
52+
used in the `hosts` file, if local.
53+
* `WP_TITLE`* - The title of the WordPress application, which contains your plugin.
54+
No quotes, because Docker does not expand variables in this file. Used during automatic
55+
installation of WordPress inside the local dev image.
56+
* `ADMIN_USER`* - This and other `ADMIN_*` variables are used to determine WordPress admin
57+
details during automatic WordPress installation with [WP-CLI][].
58+
59+
- `composer.json`:
60+
* `name` - Name of your package.
61+
* `description` - Description of your package.
62+
* `authors` - You and/or your company details.
63+
* `require` - Your project's package and platform requirements. You may want to change the PHP
64+
version if your minimal requirement is different. Don't forget to update `PHP_BUILD_VERSION`
65+
in `.env`.
66+
* `require-dev` - Your project's development requirements. Apart from tools for testing,
67+
this should (for now) contain any WordPress plugins that your plugin depends on,
68+
and WordPress. If you add plugins here, you need to mount them as volumes in
69+
`docker-compose.yml`, the `wp_dev` service. The source is the absolute path to the
70+
`vendor` dir. The destination is an absolute path to the plugin folder in the `plugins`
71+
directory of WordPress; you can use absolute paths, or the `DOCROOT_PATH` or `PROJECT_MOUNT_PATH`
72+
from the `.env` file to help make the paths more versatile. If you want these
73+
plugins to be active when the container is brought up, you need to also add these
74+
instructions to the `docker/wp-entrypoint.sh` script. You may use WP CLI for this.
75+
These instructions should go right below the line that says `# Custom setup instructions`.
76+
This way, they will only run when WordPress is ready for action. **All changes to
77+
the entrypoint script require image rebuild**: use `docker-compose down` and
78+
`docker-compose build`. This is because these changes affect the application image,
79+
which the entrypoint script is baked into.
80+
81+
In the future, this may need to go into `require`, if a plugin build script takes care
82+
of removing unnecessary plugins from `vendor` folder. This may be a good idea because
83+
the plugin _does_ actually require other plugins, but they should not be shipped with
84+
the plugin. Otherwise, completely Composer-managed WordPress installations will not
85+
automatically install other required plugins.
86+
87+
3. Spin up the dev environment
88+
89+
Run the following command in the terminal. If you use Docker Machine, you will need to
90+
start it and configure your environment first with [`docker-machine start`][] and
91+
[`docker-machine env`].
92+
93+
```bash
94+
docker-compose up wp_dev
95+
```
96+
97+
This will bring up only the dev environment and its dependencies, which right now is
98+
the database. The database is a separate service, because in a deployed environment
99+
you may choose to use a different DB server.
100+
101+
After this, add an entry to your local [hosts file][]. The host should correspond to
102+
the value of `WP_DOMAIN` from the `.env` file. The IP would be Docker machine's IP
103+
address. On Linux, this is the same as [your machine's IP address][] on the local
104+
network, and usually `127.0.0.1` (localhost) works. If you are using Docker
105+
Machine (in a non-Linux environment), use [`docker-machine ip`] to find it.
106+
107+
Now you should be able to visit that domain, and see the website. The admin username
108+
and password are both `admin` by default, and are determined by the `ADMIN_USER`
109+
and `ADMIN_PASS` variables from the `.env` file. Your plugin should already be
110+
installed and active, and no other plugins should be installed. If this is not
111+
the case, inspect the output you got from `docker-compose up`.
112+
113+
#### Updating dependencies
114+
Composer is installed into the `build` service's image. To run composer commands,
115+
use `docker-compose run`. For example, to update dependencies you can run the following:
116+
117+
```bash
118+
docker-compose run --rm build composer update
119+
```
120+
121+
If you use PHPStorm, you can use the [composer integration][], as the project
122+
is already configured for this.
123+
124+
Any changes to the project folder are immediately reflected in the dev environment,
125+
and this includes the `vendor` folder and `composer.lock` file. This is because
126+
the project's folder is mounted into the correct place in the WordPress container.
127+
128+
[Docker Machine]: https://github.com/docker/machine
129+
[WP-CLI]: https://wp-cli.org/
130+
[hosts file]: https://www.howtogeek.com/howto/27350/beginner-geek-how-to-edit-your-hosts-file/
131+
[your machine's IP address]: https://www.whatismybrowser.com/detect/what-is-my-local-ip-address
132+
[composer integration]: https://www.jetbrains.com/help/phpstorm/using-the-composer-dependency-manager.html#updating-dependencies
133+
[`container_name`]: https://docs.docker.com/compose/compose-file/#container_name
134+
[`php`]: https://hub.docker.com/_/php
135+
[`wordpress`]: https://hub.docker.com/_/wordpress
136+
[`docker-machine start`]: https://docs.docker.com/machine/reference/start/]
137+
[`docker-machine env`]: https://docs.docker.com/machine/reference/env/

0 commit comments

Comments
 (0)