Scouting Rudyard Kipling PhotoBook

This is the online photobook, initially built for scoutsgroup Scouting Rudyard Kipling, but now also open for other scoutsgroups or organisations. It features:

• Watching your own pictures online and on your own server
• Organize your pictures in albums
• Uploading images via the web portal
• User management, with different roles and permissions (admin, content creator & subscribers)
• Scouts online (sol) protected logins (Because we need to be AVG proof 🙈 )

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment chapter for notes on how to deploy the project on a live system.

Prerequisites

What things you need to install the software and how to install them

• Composer
• php 7.3 or higher (preferred latest)
• A (local) SQL database (MariaDB 10.2 or higher)
• Node.js
• NPM (installed with Node.js)
• Common sense 😉

Installing (development environment)

A step by step series of examples that tell you how to get a development env running

create a local .env

cp .env.example .env

Now setup the .env file for your environment

Minimal setup is setting up your database connection

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=photobook
DB_USERNAME=photobook
DB_PASSWORD=photobook

Install composer dependencies

composer install

Generate a local key for laravel (stored in .env)

php artisan key:generate

link the storage folder

php artisan storage:link

Migrate the database (from scratch) to the latest version

php artisan migrate

Seed the database with the bare essential data (like basic permissions and roles)

php artisan db:seed

To see a list of available artisan commands

php artisan list

As you will use artisan a lot (and we as programmers are lazy) make an alias in your .bash_profile

alias art='php artisan'

We also need to install npm with its packages

npm install

And run npm to let it generate a nice and clean looking website for you

npm run dev

Running the tests

Run all tests

composer test

The above example runs phpunit, phpcs, phpmd, and larastan. Info found in the rest of this paragraph.

phpunit - all defined tests

This command will run all php unit tests found in the test folder. this includes Unit as well as Feature tests.

./vendor/bin/phpunit

Static code analysers and coding style tests

For running all analysers at once run:

composer lint

phpcs - PHP Code Sniffer

PHP_CodeSniffer tokenizes PHP, JavaScript and CSS files and detects violations of a defined set of coding standards.

Configuration of CodeSniffer is found in phpcs.xml

PHPCS repo and guide

./vendor/bin/phpcs

phpmd - PHP Mess Detector

What PHPMD does is: It takes a given PHP source code base and look for several potential problems within that source. These problems can be things like:

• Possible bugs
• Suboptimal code
• Overcomplicated expressions
• Unused parameters, methods, properties

Configuration of MessDetector is found in phpmd.xml

PHPMD repo and guide

#executable path   
#                  tested folder or file
#                      output format
#                           configuration
./vendor/bin/phpmd app text phpmd.xml

Larastan

Discover bugs in your code without running it - phpstan wrapper for Laravel.

Configuration of Larastan is found in phpstan.neon

Larastan repo and guide

php artisan code:analyse --level=max

Deployment

If the application is already installed for the first time, skip the First time deployment paragraph and go straight to Updating.

First time deployment

We will go a little bit faster here, if you would like some more explanation, go to the above paragraph Installing, or visit the laravel documentation page

download the repo on the server (via git or filetransfer) and make sure you are in the folder of this repo.

create a local .env

cp .env.example .env

Now setup the .env file for your environment. At least setup the next fields

APP_ENV=production
APP_DEBUG=false
APP_URL=https://your.url

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your-database
DB_USERNAME=your-user
DB_PASSWORD=your-password

now run the next commands to setup the server

composer install
php artisan package:discover
php artisan key:generate
php artisan storage:link
php artisan migrate
php artisan cache:clear
php artisan config:cache
npm ci
npm run production
php artisan up

Install a cronjob to call the laravel kernel which dispatches all jobs internally, yes it has to run every minute. Laravel will determine for itself when to run the jobs.

crontab -e
# add the next line to file
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

webserver

Make sure you have the base setup the apache or nginx config correctly and routed to the public folder.

• make sure it will route to the /public folder in the repo (NOT TO THE BASE FOLDER)

apache

Laravel includes a public/.htaccess file that is used to provide URLs without the index.php front controller in the path. Before serving Laravel with Apache, be sure to enable the mod_rewrite module so the .htaccess file will be honored by the server.

If the .htaccess file that ships with Laravel does not work with your Apache installation, try this alternative:

Options +FollowSymLinks -Indexes
RewriteEngine On

RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

nginx

If you are using Nginx, the following directive in your site configuration will direct all requests to the index.php front controller:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Updating

run command

php artisan down

Upload your new repository to the server.

Make sure you do not edit or overwrite:

• .env unless edits are specified for that particular update
• vendor/
• storage/
• node_modules/

run commands

composer install
php artisan migrate

php artisan cache:clear
php artisan config:cache
npm ci
npm run production

php artisan up

Built With

• Laravel - The web framework used (with its default included packages), read more in the About Laravel section.
• Laravel IDE helper - Generates an ide helper file for better hinting. Also generates model blocks on demand.
• PHPCS - Code Sniffer tokenizes PHP, JavaScript and CSS files and detects violations of a defined set of coding standards.
• Larastan - Discover bugs in your code without running it - phpstan wrapper for Laravel.
• PHPMD - Takes a given PHP code base and looks for several potential problems within that source.
• Spatie Laravel Medialibary - The laravel media libary used
• Spatie Laravel Permission - The laravel permission libary

About Laravel

Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:

• Simple, fast routing engine.
• Powerful dependency injection container.
• Multiple back-ends for session and cache storage.
• Expressive, intuitive database ORM.
• Database agnostic schema migrations.
• Robust background job processing.
• Real-time event broadcasting.

Laravel is accessible, powerful, and provides tools required for large, robust applications.

Learning Laravel

Laravel has the most extensive and thorough documentation and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.

If you don't feel like reading, Laracasts can help. Laracasts contains over 1400 video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.

Security Vulnerabilities

• CVE details Laravel

Authors

• Friso Modderman - Initial work - adminfriso