README

Get started quickly with an USM enabled Yii2 project.

Published under MIT license.

Features

Ultimate Site Management pre-configured.
DotEnv for management of environment variables.
Docker-compose with
- PHP container running your Yii2 application
- MariaDB container with database stored in local ./runtime/database folder
- Mailpit, a mail debugging tool
Devcontainer for easy development in VS Code.

Prerequisites

Make sure the following programs are installed on your computer:

Installation

You can create your own project based on the USM Starter template using the following command (replace my-app-name with the name you want to name your project):

docker run -u "$(id -u):$(id -g)" --rm -v $PWD:/app composer create-project --prefer-dist maerduq/usm-starter my-app-name

The command starts a docker container to run the composer create-project command. This command creates your project files based on USM Starter.

Getting started for local development

With devcontainer

$ cp .env-dev.example .env - to setup you environment variables file.
Open the project folder in VS Code. VS Code will give a pop-up with a button "Reopen in Container". Click that.

Without devcontainer

$ cp .env-dev.example .env - to setup you environment variables file.
$ docker-compose up -d - to start your docker containers.
$ docker-compose exec -T app bash composer run setup-dev - for quick setup (run in your php container)

What's running

Now visit your website on http://localhost:8000/
PHPMyAdmin (for managing your database) on http://localhost:8001/
A very useful mail debugger called mailpit is available on http://localhost:8025/
And your MariaDB server is accessible via localhost:3006

Getting started for production

$ cp .env-prod.example .env - to setup you environment variables file.
Edit the values in .env to your preference.
$ ./deploy - to install everything.

Other available bash scripts

[!NOTE] When not using devcontainers, before running any command, run $ docker-compose exec -it app bash to start an interactive bash session in your Yii2 application docker container.

# composer run watch - for watchers used during development
# composer run generate-i18n - generate translation files from your views. Learn more.

Application configuration

Change the environment variables as you like using the explanation of the variables below.

Variables

Name	Description
YII_DEBUG	Whether Yii should run in debug mode (1 or 0)
YII_ENV	The Yii environment setting to run (dev, test, or prod)
DB_HOST	Host name of your database (e.g. localhost)
DB_NAME	Name of your database
DB_USERNAME	Username to access your database
DB_PASSWORD	Password to access your database
DB_CHARSET	Charset of your database (e.g. utf8mb4)
DB_SCHEMA_CACHE	Whether the schema of your database should be cached
Mail settings	---
ADMIN_EMAIL	The administrator's email
SENDER_EMAIL	The email address used as "from" when the website sends mails
SENDER_NAME	The name used as "from" when the website sends mails
MAIL_HOST	The host name of the SMTP mail server
MAIL_PORT	The port of the SMTP mail server
MAIL_USERNAME	The username with which to authenticate on the SMTP mail server
MAIL_PASSWORD	The password with which to authenticate on the SMTP mail server
MAIL_ENCRYPTED	Whether the connection with the SMTP mail server is encrypted
MAIL_TO_FILE	Whether to use the mail-to-file feature (writes sent mails to a file in `runtime/mail`)
Docker settings	---
PHP_VERSION	The PHP version used for the docker PHP container
UID	The Linux uid used for running the docker container (default: 1000)
GID	The Linux gid used for running the docker container (default: 1000)
APP_PORT	The port on which to access the USM application (default: 8000)
DATABASE_PORT	The port on which to access the MariaDB database (default: 3306)
PHPMYADMIN_PORT	The port on which to access the PHPMyAdmin application (default: 8001)
MAILPIT_PORT	The port on which to access the PHPMyAdmin application (default: 8001)

Directory Structure

  assets/             contains assets definition
  commands/           contains console commands (controllers)
  config/             contains application configurations
  controllers/        contains Web controller classes
  models/             contains model classes
  runtime/            contains files generated during runtime
  vendor/             contains dependent 3rd-party packages
  views/              contains view files for the Web application
  web/                contains the entry script and Web resources

Contributors

Paul Marcelis

Testing

[!NOTE] When not using devcontainers, before running any command, run $ docker-compose exec -it app bash to start an interactive bash session in your Yii2 application docker container.

Setup

# composer run setup-test - to setup structure for test database
# composer test - to run all tests

Additional commands

# composer test -- unit - to only run unit tests
# composer test -- --steps - to run all tests with showing every individual step
# composer test -- functional - to run only functional tests
# composer test -- unit widgets/AlertTest - to run a specific test file
# composer test -- unit widgets/AlertTest:testSingleErrorMessage - to run a single test
# composer test -- --debug - to run with debug info
# php tests/bin/yii fixture Customer - to load CustomerFixture data
# php tests/bin/yii fixture/unload "*" - to unload all data

maerduq / usm-starter

Maintainers

Package info

Statistics

Security