Tutorial: Adding Fields to Users/Characters/Etc

One of the best parts about Lorekeeper is how customizable it is. Beyond Extensions, you can go in and add entire new columns to the database to store new information that's custom to your site or to the extension you might be working on.

This tutorial will cover the basics of adding new fields to Users, though you can implement the same logic in adding fields to items, characters, etc.

The Parts of the Process

Before you get into the code, you should understand the files and terms you'll be working with.

Migrations:

Migrations are used to directly affect the columns of the database. This isn't used for putting data into the database, but instead to make new columns, tables, etc.

Found in: database/migrations

Views:

Views are the files holding the HTML code that you see. Laravel uses a blade system, which essentially means that each page you see when you load your site is actually a bunch of files fitted together, like a knife block. This allows a certain amount of customization and more importantly, allows you to reuse code in numerous locations or ways. This is how so many pages have similar sidebars - the sidebar isn't included in its entirety on every page.

Found in: resources/views

Forms:

This is what your users or admins will see when they want to edit the information in the database. It's important to note that without the back-end information (such as if you just put a text box on a page,) forms will do nothing.

Found in: resources/views

Routes:

When you navigate to a page in your browser, the site looks at the URL and then looks at the route to see where to go next, unlike static websites where you'd go to, say, index.html and see the page that's index.html in the root directory. Routes work by (usually) going to a function in a controller. GET routes are getting the information from the site in order to display it, while POST routes are sending the information from a form back to the controller to be handled.

Found in: routes

Controllers:

Controllers receive and give data. There are two main function types: GET and POST. GET generally gets information from the database and puts it together for the user to see it. This is how views are called and accessed. POST is generally used to put data into the database. Laravel has a naming convention for these for function names: GET functions generally begin with all-lowercase get (eg. getSettings, getNotifications) while POST functions usually begin with all-lowercase post (eg. postPassword, postEmail.)

Fun fact: This method of naming functions/variables with a lowercase word and then capitalized words in programming is called camelCase.

Found in: app/Http/Controllers

Services:

Services usually handle the actual placing of data into the database. While sometimes people will code the data->database handling in the Controller, it's usually better praxis to have this handling in the Service.

Found in: app/Services

Models:

Models directly relate to the table in the database. We won't need to make a new model for this, since we'll just be editing an existing table, but we will need to edit one slightly.

Found in: app/Models

Here's an analogy:

You begin your job by picking up a package of spices [the data] at the POST office [a form]. You look at your directions [the link on a form] and go along the route [route] to the restaurant worker [controller]. The package is given to the chef [service], who puts the spices [data] into the appropriate cabinets [columns in the database] in the appropriate room [table in the database.] Later, when requested by the customer [page load on a GET route], the restaurant worker [controller] gets the ingredients and puts them together. They then put the food on the plate [view] and place it on the table for the customer [you!]

Starting Out: Migrations

Before you even begin coding, you should have determined some things:

1. What information do you want added?
   1. Is it nullable - can it be completely empty/blank?
   2. Does it have a default value?
2. What form does this information take? Is it a short text input that should only be a few words? A full WYSIWYG (What You See Is What You Get) input? A boolean (True/false?)
3. Does this need to be in a new table or does it fit in one of the existing tables? This tutorial will only cover existing tables.

I recommend looking at existing migrations if there's anything similar to the field you want to add.

Migrations have a specific way to be created in a console command! I always recommend testing on a local server (like WAMPserver or XAMPP) before you mess with the database on your live server. I also recommend looking at the documentation - it's my go to when I need to add something. It makes it easier if you include the table in the migration command, though you are able to affect multiple tables in one migration if you so desire.

Go into your console commands (I use Putty for my server and Git Bash for my local, but I've seen other users use Sourcetree or VSC directly.)

php artisan make:migration add_nickname_to_users_table --table=users

It's good to make the title (add_nickname_to_users_table) as descriptive as possible whilst being succinct, but remember: this will be part of the file name for the migration file. Once you hit enter, it might take a minute to create, but it will give a nice verification saying something like:

Created Migration: 2020_08_21_104400_add_nickname_to_users_table

Now you can navigate to your database/migrations folder and see a fresh new file! If you used the form I suggested, it'll look pretty much exactly like this, but maybe with different colours:

 1 <?php
 2 
 3 use Illuminate\Support\Facades\Schema;
 4 use Illuminate\Database\Schema\Blueprint;
 5 use Illuminate\Database\Migrations\Migration;
 6 
 7 class AddNicknameToUsersTable extends Migration
 8 {
 9     /**
10      * Run the migrations.
11      *
12      * @return void
13      */
14     public function up()
15     {
16         Schema::table('users', function (Blueprint $table) {
17             //
18         });
19     }
20 
21     /**
22      * Reverse the migrations.
23      *
24      * @return void
25      */
26     public function down()
27     {
28         Schema::table('users', function (Blueprint $table) {
29             //
30         });
31     }
32 }

The two existing functions are important! up() is what gets set up when you run artisan migrate later, while down() is what's run if you ever need to roll the migration back.

I'll get back to this tutorial later.