Free Shop App

This is a "free web-shop" application based on Laravel, a popular PHP framework.

The service is intended to be used for distribution of items/goods in humanitarian aid scenarios, with a points based system for the "customers". They receive a certain amount of credits on a regular basis which then can be used to "purchase" items from the online shop. Once an order is marked as ready, the customer receives a notification by SMS informing about the modalities of the pickup of the order.

Requirements

Environment

• A web server like:
  • Apache (tested with 2.4.x)
  • Nginx
• PHP >= 8.2 with the following extensions:
  • BCMath
  • Ctype
  • Fileinfo
  • JSON
  • Mbstring
  • OpenSSL
  • PDO
  • Tokenizer
  • XML
• Composer PHP dependency manager
• A relational database like:
  • MySQL
  • MariaDB (tested with 10.4.x)
  • PostgreSQL (tested with 11.x)

3rd-party services

• [OPTIONAL] Google OAuth for backend (administrator) login
• [REQUIRED] Twilio for sending order updates by SMS
• [REQUIRED] Symfony Mailer-compatible mail service
• [OPTIONAL] Sentry for application monitoring
• [OPTIONAL] Monolog-compatible logging service for log collection and analysis

Installation

Install PHP package dependencies:

composer install

Copy .env.example to .env and change database parameters and any other parameters according to your web setup.

Generate encryption key:

php artisan key:generate

Create/migrate database tables:

php artisan migrate

Cache routes and configuration for increased performance (don't use during development!):

php artisan optimize
php artisan view:clear

Deployment

The code contains a GitHub actions definition to assemble and deploy the application to any web hosting server via SSH whenever changes are made to the 'production' branch. Credentials for the target server need to be provided as GitHub Secrets.

Task scheduler

Setup the task scheduler using the following cronjob:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

More information can be found in the Laravel documentation.

Setup backend access

Backend login relies on Google OAuth. Create API credentials according to this guide.

to obtain the client ID and client secret values.

Update the GOOGLE_* variables in .env accordingly.

Access the backend via http://your-site.com/backend

Development

Compile assets

Install and compile JavaScript and CSS files for the public web directory:

npm install
num run dev

Database seeding

To seed the database with random entries, run:

php artisan db:seed

Export language strings from code

Export translatable strings for any language:

php artisan translatable:export fr,ar,fa,so

Find untranslated strings in a language file (for example French = fr):

php artisan translatable:inspect-translations fr

Static code analysis

Run:

./vendor/bin/phpstan analyse

More information here.

Code style fixer

Run:

./vendor/bin/pint

More information here.

Set up development environment on WSL with Docker and Laravel Sail

Install WSL (Windows Subsystem for Linux), enable WSL version 2 and make it the default version. Run in an elevated command or PowerShell window:

wsl --install

See here for more info.

Install Ubuntu for WSL from the Microsoft Store.

Install Docker for Windows or Rancher Desktop.

In case of Rancher Desktop, change the settings to expose Docker to Ubuntu, and fix socket permissions as needed:

sudo chmod 666 /var/run/docker.sock
sudo usermod -aG docker ${USER}

In case of Docker for Windows, if you get an error message like /usr/bin/docker-credential-desktop.exe: Invalid argument, you can do the following:

Edit the ~/.docker/config.json file ~/.docker/config.json.

It should display something similar to this:

{
    "credsStore": "desktop.exe"
}

Change “credsStore” to “credStore” like this:

{
    "credStore": "desktop.exe"
}

Install Visual Studio Code and the Remote - WSL extension. Open a new WSL window, and checkout the code from Github.

Setup Laravel sail:

docker run --rm -u "$(id -u):$(id -g)" -v $(pwd):/opt -w /opt laravelsail/php82-composer:latest composer install --ignore-platform-reqs

Configure the sail bash alias by adding the following line to .bashrc:

alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'

Copy .env.example to .env.

Set

DB_HOST=mysql

Run the following commands:

sail up -d
sail artisan key:generate
sail artisan migrate --seed
sail npm install
sail npm run dev

Recommended software for development

• Visual Studio Code
• Git
• GitHub Desktop
• XAMPP (on Windows)
• Composer
• NodeJS/NPM

Productive docker image

Adapt the environment variables in docker-compose-prod.yml according to your setup.

Build the docker image:

docker-compose -f docker-compose-prod.yml build

Run the docker image:

docker-compose -f docker-compose-prod.yml up -d

Execute Laravel artisan command inside the container (if needed):

docker-compose exec app php artisan YOUR_COMMAND