Mapping out your Laravel project

Every project has to kick off somewhere.  Yep well that's a no brainer.  However, the number of projects that I've seen where the planning step has been omitted is too high.  A throughly planned out project with as many features scoped before you start coding is critical in completing a project.  Whilst projects and their requirements are always fluid, the initial critical scoping is so important.

Fail to plan, planning to fail

There is no one way to plan.  Yes I've seen staff that have to follow the company formula.  Great idea for consistency.  However, if there is no flexibility in the process.  No post reviews.  No challenges up the line.  Similar errors pop up in each project.  That said, I've found each company has their way.  Whilst there are overlaps, a plan is not set.  Meaning at the end of each project, review what worked well and what parts of the process can be improved.  These processes will be dependant on how your mind works. For a company how your collective minds work.  For me, I'm a visual person, I like to plan on paper.  A4 / A3 pads are great.  Even architectual paper (it's semi transparent) is cool to work on.  Getting away from a screen can be magic.  Drawing out the way I picture the screens looking and then working backward into how I would code it.  Also mapping the database and content structures.  Once this has been consolidated I convert this to a written project plan usually in Google (for sharing) and at times with support from a mind mapping tool. The key here is it doesn’t matter how you plan, just that you do it.

Adding Authentication Scaffolding

Laravel has a separate first-party package for generating common scaffolding that makes setting up authentication easy as. Install the UI composer package by using the command:

lando composer require laravel/ui

I discovered a raft of errors.  Well actually one core error.  The PHP version is below 8.x... specifically 7.4.  So my screen filled with the following

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires php ^8.0.2 but your php version (7.4.28) does not satisfy that requirement.
  Problem 2
    - laravel/framework is locked to version v9.7.0 and an update of this package was not requested.
    - laravel/framework v9.7.0 requires php ^8.0.2 -> your php version (7.4.28) does not satisfy that requirement.
  Problem 3
    - nunomaduro/collision is locked to version v6.2.0 and an update of this package was not requested.
    - nunomaduro/collision v6.2.0 requires php ^8.0.0 -> your php version (7.4.28) does not satisfy that requirement.
  Problem 4
    - spatie/laravel-ignition is locked to version 1.2.0 and an update of this package was not requested.
    - spatie/laravel-ignition 1.2.0 requires php ^8.0 -> your php version (7.4.28) does not satisfy that requirement.
  Problem 5
    - symfony/deprecation-contracts v3.0.1 requires php >=8.0.2 -> your php version (7.4.28) does not satisfy that requirement.
    - fakerphp/faker v1.19.0 requires symfony/deprecation-contracts ^2.2 || ^3.0 -> satisfiable by symfony/deprecation-contracts[v3.0.1].
    - fakerphp/faker is locked to version v1.19.0 and an update of this package was not requested.

You can also try re-running composer require with an explicit version constraint, e.g. "composer require laravel/ui:*" to figure out if any version is installable, or "composer require laravel/ui:^2.1" if you know which you need.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.

A check of the PHP version being used:

php -v

Deivered the following response

PHP 8.1.2 (cli) (built: Jan 21 2022 04:47:26) (NTS)
name: safs
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Xdebug v3.1.3, Copyright (c) 2002-2022, by Derick Rethans
    with Zend OPcache v8.1.2, Copyright (c), by Zend Technologies

Whereas, the app wasn't accessing PHP via the system, instead it was through lando.  So the command I needed to execute was:

lando php -v

Response 

PHP 7.4.28 (cli) (built: Mar 18 2022 01:38:32) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.28, Copyright (c), by Zend Technologies

I had already written an article about this issue, 'lando PHP version issue 7.4.x instead wanting >= 8.0.2'.  If you have the same, follow the steps outlined there and then come back to this article to continue.

Post running the change to lando php version.  When I rebuilt lando, I ended up with a COMPOSE_HTTP_TIMEOUT error.  So I wrote how I resolved it on 'lando COMPOSE_HTTP_TIMEOUT error'.

Now I can attempt the authentication scaffolding again.

lando composer require laravel/ui

Looking much better... as the response was

Using version ^3.4 for laravel/ui
./composer.json has been updated
Running composer update laravel/ui
Loading composer repositories with package information
Info from https://repo.packagist.org: #StandWithUkraine
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking laravel/ui (v3.4.5)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Downloading laravel/ui (v3.4.5)
  - Installing laravel/ui (v3.4.5): Extracting archive
Generating optimized autoload files
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
> @php artisan package:discover --ansi
Discovered Package: laravel/sail
Discovered Package: laravel/sanctum
Discovered Package: laravel/tinker
Discovered Package: laravel/ui
Discovered Package: nesbot/carbon
Discovered Package: nunomaduro/collision
Discovered Package: spatie/laravel-ignition
Package manifest generated successfully.
78 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
> @php artisan vendor:publish --tag=laravel-assets --ansi --force
No publishable resources for tag [laravel-assets].
Publishing complete.

Finally I'm moving forwards.... for now!

Back on task - scaffolding.  The UI package delivers some commands for setting up scaffolding for tools like React, Vue, and Bootstrap.  Execute the following to generate routes, controllers, views and other files necessary for auth:

php artisan ui bootstrap --auth

The response from this command says it all...

Bootstrap scaffolding installed successfully.
Please run "npm install && npm run dev" to compile your fresh scaffolding.
Authentication scaffolding generated successfully.

We need to compile the CSS UI and this can be achieved with the following command

npm install

# Build dev assets
npm run dev

# Otherwise use a watcher to automatically update changes
npm run watch

The ball is rolling

Now the momentum is building and we are beginning to make head waves in to our Laravel site.

Links list

Using the following command you will build a link list

php artisan make:migration create_links_table --create=links

Now adjust the schema of the links list.  Edit the file that the command above created. It will be located at database/migrations/{{datetime}}_create_links_table.php.

Schema::create('links', function (Blueprint $table) {
    $table->increments('id');
    $table->string('title');
    $table->string('url')->unique();
    $table->text('description');
    $table->timestamps();
7});

Save the file and run the migration:

php artisan migrate

Database connection refused error

If whilst running the above command you hit an error like

SQLSTATE[HY000] [2002] Connection refused (SQL: select * from information_schema.tables where table_schema = laravel and table_name = migrations and table_type = 'BASE TABLE')

  at vendor/laravel/framework/src/Illuminate/Database/Connection.php:716
    712▕         // If an exception occurs when attempting to run a query, we'll format the error
    713▕         // message to include the bindings with SQL, which will make this exception a
    714▕         // lot more helpful to the developer instead of just the database's errors.
    715▕         catch (Exception $e) {
  ➜ 716▕             throw new QueryException(
    717▕                 $query, $this->prepareBindings($bindings), $e
    718▕             );
    719▕         }
    720▕     }

      +36 vendor frames
  37  artisan:37
      Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))

As stated in the error, the issue is with access to the MySQL db or lack of connection.  If you are running locally via lando, check that you have run the lando start command.

lando start

You might find that lando start doesn't kick start the app and remove the error.  What we know, the error is based on a connection issue with the database.  Can you connect to the database?  Well find out by running the command

lando mysql

Success?  If so you will see a response similar to

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1
Server version: 5.7.29 MySQL Community Server (GPL)
// ... more details ... //

Maybe check the user and database exist... leam more about completing this in the article 'Create a MySQL database using command line (CLI)' ~ https://www.codebales.com/create-mysql-database-using-command-line-cli

The solution to this issue was doing the following post the Create a MySQL database from the article above.

lando destroy -y && lando rebuild -y  && lando start