Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/enterwell/wp-starter
Start a new project with backend (PHP), frontend (jQuery, React, Sass, Webpack) and Wordpress CMS to take care of them all
https://github.com/enterwell/wp-starter
jquery php react sass wordpress
Last synced: 25 days ago
JSON representation
Start a new project with backend (PHP), frontend (jQuery, React, Sass, Webpack) and Wordpress CMS to take care of them all
- Host: GitHub
- URL: https://github.com/enterwell/wp-starter
- Owner: Enterwell
- License: other
- Created: 2021-01-29T12:37:16.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-02-26T15:13:36.000Z (10 months ago)
- Last Synced: 2024-02-26T16:34:39.723Z (10 months ago)
- Topics: jquery, php, react, sass, wordpress
- Language: PHP
- Homepage:
- Size: 76.8 MB
- Stars: 7
- Watchers: 5
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: license.txt
Awesome Lists containing this project
README
Enterwell WP starter
Start a new project with backend (PHP), frontend (jQuery, React, Sass, Webpack) and
Wordpress CMS to take care of them all.
[](https://github.com/Enterwell/wp-starter/actions/workflows/github-actions-build-qa.yml)
[](https://github.com/Enterwell/wp-starter/issues)
[](https://github.com/Enterwell/wp-starter/graphs/contributors)
[](https://github.com/Enterwell/wp-starter/pulls)
> ✏️ **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 🔨](#-requirements).
Clone this project into your web projects directory (`/var/www/`):
```bash
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`):
```txt
127.0.0.1 .local
```
Add new virtual host configuration file `.local` to your webserver (`/etc/nginx/sites-available`):
```nginx
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/;
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 .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/.local /etc/nginx/sites-enabled/.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`):
```bash
yarn install
```
Run node script that'll rename all your files/folders and create project structure:
```bash
yarn init-project
```
Navigate to **plugin folder** (`$ROOT/wp-content/plugins/`) and install composer dependencies:
```bash
composer install
```
Navigate to **theme folder** (`$ROOT/wp-content/themes/`) and install composer and node dependencies:
```bash
composer install
yarn install
```
Continue by starting the webpack server (in `$ROOT/wp-content/`) that'll automatically open the page in browser:
```bash
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:
```php
//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](#-run-project)
- [🔨 Requirements](#-requirements)
- [🪄 Purpose and capabilities](#-purpose-and-capabilities)
- [🏛 Project structure](#-project-structure)
- [🏗 Build project](#-build-project)
- [🚀 Deploy project](#-deploy-project)
- [🧪 Testing](#-testing)
- [🪪 License](#-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](wp-content/themes/ew-theme/assets/gutenberg/README.md) (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](wp-content/themes/ew-theme/classes/class-ew-theme.php)
## 🏛 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](azure-pipelines-build.yml) 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`):
```bash
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`):
```bash
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](azure-pipelines-build.yml) 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](#-build-project), your files are ready to be transferred to your public environment.
> 🔔 [Read our docs](.ansible/README.md) 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](https://phpunit.de/) 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](https://phpunit.readthedocs.io/en/9.6/index.html)
> - [Wordpress PHPUnit overview](https://make.wordpress.org/core/handbook/testing/automated-testing/writing-phpunit-tests/)
> - [Premise on which PHPUnit is set up in this starter](https://make.wordpress.org/cli/handbook/misc/plugin-unit-tests/)
#### 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](https://make.wordpress.org/cli/handbook/misc/plugin-unit-tests/#running-tests-locally): Linux environment, svn package, git package (and PHP of course)
- navigate to `$ROOT/wp-content/plugins/` 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
```bash
./vendor/bin/phpunit
```
> 🔔 Tests need to be named as `test-` and have to be saved as a `.php` file.
| **Unit** | **Integration** |
|----------|-----------------|
| `$PLUGIN_DIR/tests/unit` | `$PLUGIN_DIR/tests/integration` |
| extend `WP_UnitTestCase` class | extend `Plugin_Test_Case` class |
| Typically used to test isolated parts of the code that are not integrated with other services, repositories etc. These are usually some **helper classes, functions** etc. They extend the `WP_UnitTestCase` class that gives the access to assertion functions, fixtures etc. (more in Useful Links above) | In this context, tests that test the operability of features as a whole. In plugin, this would be all tests with programming logic that talks to databases and other third-party services, API endpoint tests, creation of permanent objects etc. Everything that will confirm us that our bigger feature is working even when smaller parts of the feature are refactored (not always the case). They extend the `Plugin_Test_Case` class that wraps`WP_UnitTestCase` with common logic (like activating the plugin and creating database tables) |
### 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](https://caniuse.com/).
## 🪪 License
Project is licensed under [GNU Public License, **GPL v2 (or later)**](license.txt). This is a [requirement by WordPress](https://wordpress.org/about/license/)