Parf Edhellen

This is the source code for elfdict.com, a non-profit, free dictionary online for Tolkien's languages. Maintained by Leonard. Follow me on twitter at @parmaeldo.

Service configuration

Ensure that the following dependencies are installed:

php8.1-curl php8.1-gd php8.1-intl php8.1-mbstring php8.1-mysql php8.1-readline php8.1-xml php8.1-zip

Configure the database using the model files. Execute the script files in ascending order, starting with schema.sql. You can apply the migrations once you've got Laravel configured. To configure Laravel, run the following commands sequentially:

gh repo clone galadhremmin/Parf-Edhellen
cd Parf-Edhellen/src
npm install
mkdir bootstrap/cache
chmod 755 bootstrap/cache
mkdir -p storage/framework/{sessions,views,cache}
chmod -R 775 storage/framework
cp .env.example .env
vim .env # configure appropriately
composer install
php artisan key:generate
php artisan storage:link

Always make sure to follow Laravel's guidelines and best practices before moving the app into production.

Development

Run Parf Edhellen locally by executing php artisan serve. You need to compile the TypeScript application by running npm run watch.

Make sure to run Node v16. Parf Edhellen isn't currently compatible with Node 17+.

Want to help out?

If you are interested in helping out, please get in touch with galadhremmin. You can also help us by donating. Please visit elfdict.com for more information.

Documentation

Audit trail

The audit trail consists of activities. Activities are specified as constants within the App\Models\AuditTrail class, and utilised throughout the application. The App\Repositories\AuditTrailRepository contains the necessary functionality for converting activities (which are integers) into human-readable strings.

Note: audit trail model objects with the property is_admin set to 1 (= true) can only be seen by administrators.

Cookies

The following cookie names are used by the application:

Cookie name	Description
ed-usermode	Administrators can give a cookie with this name the value incognito to hide their activity.

System errors

The schema system_errors contain information about client-side as well as server-side exceptions. Common exceptions (404 Page not found, 401 Unauthorized, etc.) are separated from the rest by the is_common column.

Uncaught client-side exceptions are caught by the onerror event, passed to a web API, and logged. Refer to the API documentation for more information.

Coding style

• \t must be replaced with four spaces for JavaScript and PHP, else two spaces.

• PHP is written in camelCase with exception for classes and interfaces, which are capitalized.

• SQL is written in upper case.

• Always a single space between statements, brackets and paranthesis.

• Curly brackets are positioned on a new line for methods, interfaces and classes, else the first bracket is positioned on the same line as the clause. Example:

  class A
  {
      public function sayHello() 
      {
          if (empty($this->_name)) {
              echo 'Hello!';
          } else {
              echo 'Hello, '.$this->_name;
          }
      }
  }
  

• Conditional operators are restricted to one line, unless the resulting operation is long enough to warrant a split, at which point the first new line is positioned before the question mark, and the second one new line before the colon. Example:

  {
      $fruitName = $fruit instanceof Apple ? 'apple' : 'fruit';
      $customer = $fruit instanceof Apple
          ? FruitVendor::sell($fruit, $appleAdvert, true) 
          : FruitVendor::discard($fruit);
  }
  

The source code is provided as-is. The code does not, in any shape or form, reflect best coding practices; it's a non-profit hobby project of mine.

License

ElfDict (Parf Edhellen; elfdict.com) is licensed in accordance with AGPL.