Sometimes, especially when you're at the beginning of your career, it can seem that you're following the instructions and getting nowhere - while everyone else seems to find it terribly easy.
It can be pretty disheartening, and I want to describe a couple of ways I experience exactly the same thing even after, well, decades. So here I am, trying to detail the stumbles and bumbles I make trying to get things to work. This is my first post on the subject, but I hope to make more.
Let's learn Laravel.
Laravel strives to provide an amazing developer experience [...]
Whether you are new to PHP web frameworks or have years of experience [...]
Laravel is touted as being the "developers' framework, at least in PHP circles, because it's more bare-bones than the others and it takes simple yet strict architecture decisions. I've done a few other PHP frameworks - Drupal 7, Drupal 8+, Symfony, WordPress, Concrete5, PrestaShop, CodeIgniter off the top of my head - so I'm not going into this unprepared.
I'll start from a barebones laptop and see how far I get.
Installing prerequisites (tldr; issues: zero, confidence: supreme)
Before creating your first Laravel application, make sure that your local machine has PHP, Composer, and the Laravel installer installed. In addition, you should install either Node and NPM or Bun so that you can compile your application's frontend assets.
OK. Not a problem. I'll apt install myself some of that PHP, get composer from... getcomposer.org, and figure out how to install the "Laravel installer" next. Aparently my distro has Node 22 out the box, or it installed when I set something else up earlier, so that should be covered.
$ composer global require laravel/installer
Boom. Done. No problems yet, we're off to a good start and confidence is at an all-time high.
Setting up a new Laravel project (tldr; issues: some, confidence: high)
$ laravel new example-app
zsh: command not found: laravel
Oh. Maybe I have to revisit that supreme confidence thing.
So it seems that composer doesn't install anything into regular binary paths and the composer installer doesn't do anything to add itself to the system path either. I've never really had to face that before, since I've directly run composer-installed binaries from whatever path they appear in. For example, with Drupal, there's vendor/drush/drush/drush or vendor/bin/drush depending on which version you're running. Do I need to add myself a symlink or alias or find the laravel binary wherever composer added it, "globally"?
I don't know, so I have to search for this.
I find some clues on a Stack Overflow answer: you can find the composer binary directory with composer global config bin-dir --absolute, and apparently in modern versions of composer everything with an executable command gets it put into that directory rather than losing itself to the hierarchy.
Good. I can add something to my startup script to put that in my path... except that command produces more than just the path...
$ composer global config bin-dir --absolute
Changed current directory to /home/moopet/.config/composer
/home/moopet/.config/composer/vendor/bin
... and I can't use that whole string as a directory. Maybe I'll need to use tail to get the last line, or something. Wait, no there's another comment on this SO answer which includes the --quiet flag. What does that do? I'll try composer --help:
Usage:
list [options] [--] [<namespace>]
Well, uh, turns out that running --help on a bare composer command actually gives help for the list subcommand rather than composer itself. That had me stumped for a minute.
-q --quiet Do not output any message
Hmm, that doesn't sound useful! We want some output. What else is there?
--raw To output raw command list
--format=FORMAT The output format (txt, xml, json, or md) [default: "txt"]
Maybe it's one of these?
The "--raw" option does not exist.
The "--format" option does not exist.
Nope. Like I thought, these are options to list and not general use flags.
Let's run it with --quiet anyway, just for poops and funsies:
$ composer global config bin-dir --absolute --quiet
/home/moopet/.config/composer/vendor/bin
Well, what do you know, it worked. It's just badly documented.
I'll pop that into my shell startup script with a little guard code and we can continue:
if command -v composer >/dev/null; then
export PATH=$(composer global config bin-dir --absolute --quiet):$PATH
fi
Setting up a new Laravel project, take 2 (tldr; issues: some, confidence: wavering)
This time laravel new example-app launches, and prompts me for a few things. I accept the defaults, since I haven't read far enough in the documentation to know the difference, except for the starter kit. I choose, "Breeze" because that's how it is in the documentation.
It starts the installation process and all looks good until:
- Root composer.json requires laravel/pint ^1.0 -> satisfiable by laravel/pint[v1.0.0, v1.1.0, v1.1.1].
- laravel/pint[v1.0.0, ..., v1.1.1] require ext-xml * -> it is missing from your system. Install or enable PHP's xml extension.
Wait, PHP needs the XML extension? That was never listed as a requirement! OK, I'll do a quick apt install php-xml.
Good, all installed. I'll run the setup again.
laravel new example-app
In NewCommand.php line 789:
Application already exists!
Oh.
So the installer got part way through, failed because it hadn't verified its dependencies, and has left the app in a broken state. That's not a good sign. Laravel's on, what, version 11?
Surely they'd have basic up-front requirements checking by now? Oh well. I'll just rm -r example-app and start again, nothing lost because I haven't really started yet.
Long story short1 the next missing dependency was the the DOM extension, or maybe the XML extension. Or maybe the cURL extension.
- phpunit/phpunit[11.0.1, ..., 11.4.3] require ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.
- Root composer.json requires phpunit/phpunit ^11.0.1 -> satisfiable by phpunit/phpunit[11.0.1, ..., 11.4.3].
So I need to install php-dom? No. Try some others. Stack Overflow again. Turns out I need to install php-curl. Riiiight.
Onward. rm -r the directory and run through the setup wizard again.
Setting up a new Laravel project, take 3 (tldr; issues: hngg, confidence: still wavering but bolstered by recent problem-solving success)
It prompts me for which database server to use. All of them say, "Missing PDO extension" next to them.
Sigh.
I break out of the installer, delete the whole directory again, apt install php8.3-mysql because there's no direct php-pdo package and no alias for php-mysql that works either, so I've done some tiresome apt searching.
Illuminate\Database\QueryException
SQLSTATE[HY000] [2002] Connection refused (Connection: mysql, SQL: select exists (select 1 from information_schema.tables where table_schema = 'laravel_example_app' and table_name = 'migrations' and table_type in ('BASE TABLE', 'SYSTEM VERSIONED')) as 'exists')
What the what now? At no point has this installer asked me for connection details for a database. And it's trying to run SQL commands against... something. Who knows?
As it happens, I have a MySQL server running on another host in my LAN and was prepared to use that (even though I'll note that bringing your own database was not listed as a requirement for Laravel). I guess I should have installed SQLite, maybe that would have worked, since it won't need any credentials.
sudo apt install php8.3-sqlite
Try again.
rm -r example-app
laravel new example-app
...
Great success. Hacker voice "I'm in". For the win. Success kid.
Conclusion
I made it? I think.
But if someone had asked me how long this might take, then based off the enthusiastic documentation and reputation, I'd have said 20 minutes. If I was doing it for work, my project manager would have doubled or quadrupled that based on experience of developer estimates.
How long did it really take me? An hour or so one evening and an hour or so the next day. I wasn't rushing, but it wasn't straightforward.
And you know what? I'm not happy with it. It's not using MySQL, because that part of the installer appears to be completely broken. I'm using SQLite and that's one step further from what would be going on in a real production environment. So there're definitely some things left on the TODO list before I can get going with the actual tutorials.
But it runs. The build steps claim they went without a hitch.
I'm ready for the next phase: fixing the JsonException, Syntax error and ProcessTimedOutException that appear in the console as soon as I open the demo page in my browser.
Uh-oh.
If only things worked out the box, eh.
-
Chorus: too late ↩
Top comments (0)