Enterwell WP starter

Start a new project with backend (PHP), frontend (jQuery, React, Sass, Webpack) and
Wordpress CMS to take care of them all.

✏️ Note: Make sure you update this document with your project's information and remove this note before publishing.

⚡ Run project

First, go ahead and see if your environment meets the recommended requirements 🔨.

Clone this project into your web projects directory (/var/www/):

git clone https://github.com/Enterwell/wp-starter.git

🔔 If you already have a git repo for your new project, clone this starter into that project, move everything except .git folder from starter folder to your project root folder and remove (now empty) starter folder from your project.

Add your wanted project local URL to hosts file (/etc/hosts):

127.0.0.1 <project_name>.local

Add new virtual host configuration file <project_name>.local to your webserver (/etc/nginx/sites-available):

server {
        listen 80;
        listen [::]:80;

        # Limit file upload to 8 MB
        client_max_body_size 8M;

        # Route to project code root (where page is loaded from)
        root /var/www/<repo_name>;
        index index.html index.htm index.php;

        # Sets domain for this configuration
        # Every request with this domain will be routed to this conf
        server_name <project_name>.local;

        # Run all static files directly
        location / {
                try_files $uri $uri/ /index.php?$args;
        }

        # Handle .php files through some PHP service
        location ~ \.php$ {
                include snippets/fastcgi-php.conf;
                # Run PHP files through PHP-FPM service
                # Change version if needed
                fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        }
}

🔔 Update conf file based on your wanted local domain, project folder and PHP version and link it to enabled sites sudo ln -s /etc/nginx/sites-available/<project_name>.local /etc/nginx/sites-enabled/<project_name>.local. Reload web server afterwards: sudo service nginx reload

Rename files, folders, namespaces etc. by editing $ROOT/.scripts/config.js. Please keep up with the naming of each one of them based on the current convention used (noted in the file).

Install node packages in project root folder ($ROOT):

yarn install

Run node script that'll rename all your files/folders and create project structure:

yarn init-project

Navigate to plugin folder ($ROOT/wp-content/plugins/<plugin_name>) and install composer dependencies:

composer install

Navigate to theme folder ($ROOT/wp-content/themes/<theme_name>) and install composer and node dependencies:

composer install
yarn install

Continue by starting the webpack server (in $ROOT/wp-content/<theme_name>) that'll automatically open the page in browser:

yarn start

You are welcomed with WordPress installation steps that are self-descriptive to fill out on your own.

🔔 You'll be prompted with entering a database for your project. If you haven't done that already, create an empty database (usually named wp_) and enter database access credentials (usually root with empty password, based on your conf)

Outcome of the previous installation is the wp-config.php file in project root ($ROOT). We'll make this changes in it in order to see debug information while developing:

//define( 'WP_DEBUG', false );

/* Add any custom values between this line and the "stop editing" line. */
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'WP_DEBUG_LOG', true );
/* That's all, stop editing! Happy publishing. */

That's it! 🎉 Login to WordPress dashboard and turn on your plugin and your theme.

🔔 To clean up installation scripts and files we no longer need, run bash cleanup.sh in project root ($ROOT)

Good luck developing! 🖥️

📖 Table of contents

• ⚡ Run project
• 🔨 Requirements
• 🪄 Purpose and capabilities
• 🏛 Project structure
• 🏗 Build project
• 🚀 Deploy project
• 🧪 Testing
• 🪪 License

🔨 Requirements

List of recommended (and tested) environment requirements:

• Linux distribution (native or WSL)
• Nginx v1.18.0+
• MySQL/MariaDB distribution v10.6.11+ (or MySQL alternative)
• PHP v8.2+ with PHP-FPM
• Composer v2+
• NodeJS v18+ (LTS)
• Git
• Yarn v1

🔔 It is possible to run this on XAMPP, Laragon (and on Apache) or other environments with other versions, but this is the tested and most used stack (LEMP)

🪄 Purpose and capabilities

⛏ TODO: explain purpose of this starter, what can you do with it, short summary of its architecture and what does each part of it do, link to Gutenberg documentation (and translate it to ENG)

Additional notes

• User endpoint is disabled by default because of security reasons. Depending on the project needs, this can be enabled here

🏛 Project structure

⛏ TODO: visualize project structure, where are files meant to be created and worked on

🏗 Build project

🔔 There is an Azure Pipelines YAML file prepared for building the project that you can use instead of doing the next steps manually

Due to being an interpreted language, PHP does not need to be built. On the other hand, we need Composer dependencies installed for production purposes. To remove dev packages used in development, run the command in plugin and theme folders ($PLUGIN_DIR and $THEME_DIR):

composer update --no-dev

We do use Javascript that's wrapped with Webpack.

Webpack files are built and served in $THEME_DIR/assets/dist folder by running the command in theme folder ($THEME_DIR):

yarn build

There are also some files in the project that we don't need on the server. To see which ones those are, please check the Removed unused files for artifact build script in the pipeline file.

⚠ That script is meant to be run on the build agent environment. Cherry-pick which commands you want to run because the script deletes all git files, documentation etc. that you need in your repository.

That's it 🥳

🚀 Deploy project

After 🏗 building the project, your files are ready to be transferred to your public environment.

🔔 Read our docs on Ansible and how you can automate the preparation of the environment in couple of minutes.

🧪 Testing

Due to using a couple of technologies together in this starter project, they are tested in somewhat different ways. We'll explain each one of them: which technologies are tests ran on, how are they written and how to run them.

PHP

All server-based programming logic is usually written in PHP in a custom plugin developed for each project. That's why the testing for this is prepared on a plugin basis in plugin folder. There is some logic written in PHP in theme as well but theme typically calls plugin methods and functions, so we don't often test these (which we should).

PHP code is tested with PHPUnit and based on practises pushed by WordPress. It is based on the same thing but WordPress added its bits and pieces to make it "better".

📚 Useful links

• PHPUnit documentation
• Wordpress PHPUnit overview
• Premise on which PHPUnit is set up in this starter

Setup

To start testing your code with PHPUnit, we need an empty WordPress installation and an empty database. Here are some steps to get you to that point:

🔔 Requirements: Linux environment, svn package, git package (and PHP of course)

• navigate to $ROOT/wp-content/plugins/<plugin_name> and run composer install to install PHPUnit
• in the same folder run bash bin/install-wp-tests.sh wp_starter-test root '' localhost latest
  • this will install you a fresh WordPress installation to $PLUGIN_DIR/tests/tmp and WordPress testing tools. It also creates a database based on parameter sent to the command above
  • wp_wp-starter-test is the name of the test database (all data will be deleted!)
  • root is the MySQL username
  • '' is the MySQL user password
  • localhost is the MySQL server host
  • latest is the WordPress version; could also be 3.7, 3.6.2 etc.
• run tests with ./vendor/bin/phpunit in $PLUGIN_DIR

When environment is set up once for a project, every next test run is triggered by calling

./vendor/bin/phpunit

🔔 Tests need to be named as test- and have to be saved as a .php file.

Manual

Testing manually while developing and before production is also a must-do because we still can't cover 100% of project with tests, and it's not possible to test every case. This is usually the case for presentation side of the project (styling).

Mobile

Project can be run so that everything is proxied to one port that we can then access from our mobile devices to test it in real environment.

• navigate to $PROJECT_DIR/wp-content/themes/ew-theme and start webpack server with yarn start
• in the same folder run yarn start-mobile that starts Browsersync package
• command will show you the External address that you can access from your mobile phone

Desktop

This is usually done while developing. It is often them case that developers open their websites in different browsers to check if everything looks the same based on different browser engines.

🔔 You can check which features work on which browsers (and their versions) on CanIUse website.

🪪 License

Project is licensed under GNU Public License, GPL v2 (or later). This is a requirement by WordPress