Stack for this post:

• Laravel 11.5.0
• PHP 8.3.6
• MySQL 8.1

<?php

use Database\Seeders\PlacesSeeder;
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('places', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->geography('coordinates', 'point');
        });

        (new PlacesSeeder())->run();
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('places');
    }
};

<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class PlacesSeeder extends Seeder
{
    /**
     * Run the database seeds.
     */
    public function run(): void
    {
        $montgomery = [
            'name' => 'MONTGOMERY',
            'coordinates' => DB::raw('ST_SRID(Point(50.838006, 4.40897), 4326)'),
        ];

        DB::table('places')->insert([$mongtomery]);
    }
}

Coordinates in the database, why? ​

Among all MySQL spatial functions, a bunch of them support computations, which might be handy in some scenarios. I absolutely don’t need this for now and I could as well use a JSON type or a VARCHAR to store the latitude and longitude of a place, but I gave it a try since I like to express data in a meaningful way, and for science’s sake!

Create a field for coordinates in a Laravel migration ​

In Laravel, you can use the geography column type to declare a POINT in your table migration:

Schema::create('places', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->geography('coordinates', 'point');
});

The actual SQL query ran by this migration:

CREATE TABLE `places` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(255) NOT NULL,
  `coordinates` point /*!80003 SRID 4326 */ NOT NULL,
  PRIMARY KEY (`id`)
);

The comment in the coordinates field shows it uses a SRID of 4326, which is one of the most common ways to project spatial data on a 2D map. It seems that’s what SRID are all about.

Insert geographic coordinates in a table ​

Let’s see how to store an entry containing geographic coordinates, first using plain SQL, then using Laravel.

Insert geographic coordinates using plain SQL ​

You might think it’s straightforward to insert an entry in this table using the Point MySQL function:

INSERT INTO `places` (`name`, `coordinates`)
VALUES
	('MONTGOMERY', Point(50.838006, 4.40897))

But this query actually fails and throws:

The SRID of the geometry does not match the SRID of the column 'coordinates'. The SRID of the geometry is 0, but the SRID of the column is 4326. Consider changing the SRID of the geometry or the SRID property of the column.

We need to attach a SRID to that point, using the ST_SRID function:

INSERT INTO `places` (`name`, `coordinates`)
VALUES
	('MONTGOMERY', Point(50.838006, 4.40897)) # [!code --]
	('MONTGOMERY', ST_SRID(Point(50.838006, 4.40897), 4326)) # [!code ++]

Now it works, and our table entry contains POINT(50.838006 4.40897),4326 in coordinates.

Insert geographic coordinates using Laravel DB ​

In Laravel, I initially thought this would work:

$montgomery = [
    'name' => 'MONTGOMERY',
    'coordinates' => 'ST_SRID(Point(50.838006, 4.40897), 4326)',
];

DB::table('places')->insert([$mongtomery]);

But unlike the previous plain SQL request, it fails:

SQLSTATE[22003]: Numeric value out of range: 1416 Cannot get geometry object from data you send to the GEOMETRY field

This is a bit unexpected, so let’s debug! We can inspect the generated SQL query with the undocumented DB::pretend method:

dd(DB::pretend(fn() => DB::table('places')->insert([$mongtomery])));

We see the ST_SRID function is now unfortunately wrapped by quotes, it’s why it fails.

INSERT INTO `places` (`coordinates`, `name`)
VALUES
    ('ST_SRID(Point(50.838006, 4.40897), 4326)', 'MONTGOMERY')

To work around this, we need to prepare the SQL statement using DB::raw :

$montgomery = [
    'name' => 'MONTGOMERY',
    'coordinates' => 'ST_SRID(Point(50.838006, 4.40897), 4326)', 
    'coordinates' => DB::raw('ST_SRID(Point(50.838006, 4.40897), 4326)'), 
];

DB::table('places')->insert([$mongtomery]);

With this change, the generated SQL query is now correct. 👍

It’s somehow weird that Laravel provides a convenient way to create a spatial database column but absolute nothing when it comes to actually dealing with related read-write operations. On the other hand, looking at the spatial specifics (number of possibilities, functions and database engines), it’s probably wiser to keep this out the scope of the framework.

Sometimes you end up stashing code, then at some point those stashes get cleaned. And one day, you may be like:

Ooops, I think I just deleted stashes that I needed! Are they lost forever? 😨

Fortunately, I managed to recover them. Here’s the two-steps procedure that worked for me after going through various readings (and others), and also some general tips.

Step 1: list lost stashes ​

In your project where stashes are trashed:

git fsck --unreachable | grep commit | cut -d ' ' -f3 | xargs git log --merges --no-walk

It returns a list of lost stashes, ordered by date.

commit 7754fed19955d2958d952ab2836b22631b036b5
Merge: f0a125c 36f580 e508036
Author: Mehdi Merah <xx@xxx.com>
Date:   Fri Apr 27 16:41:17 2018 +0200

    On regions-components: After Regions component

commit 43c45c94caadcc87d783064624585c194f4be8
Merge: 13703fd bc8220e 4005629
Author: Mehdi Merah <xx@xxx.com>
Date:   Sat Apr 21 20:03:44 2018 +0200

    On master: Before Regions components

commit bb615e44ed99b5a5622ead0c4bbb7b4acc19767
Merge: c6a7b3 127203e 45dcc54
Author: Mehdi Merah <xx@xxx.com>
Date:   Sat Apr 7 19:39:50 2018 +0200

    On master: Wololo

# So, basically this anatomy:

commit {stash commit hash}
Merge: {parent commit hash…}
Author: {author name} <{author email}>
Date:   {stash date with timezone}

    On {branch name}: {stash commit message}
(END)

• To quit the list of stashes, press the Q key.
• To navigate in a long stashes list, use the up and down arrows.
• For Windows user, maybe johnwait’s comment will help you during the battle:

Step 2: send a lost stash back where it comes from ​

Let’s use the commit hash of the second stash (from the previous list):

git update-ref refs/stash 4b3fc45c94caadcc87d783064624585c194f4be8 -m "My recovered stash"

And that’s it! You’ll find your stash as usual, using git stash list or by having a look in your favorite Git client.

Gotchas ​

1. I still can’t see my recovered stash ​

Retry using the --create-reflog parameter (thanks studoggithub):

git update-ref refs/stash 4b3fc45c94caadcc87d783064624585c194f4be8 --create-reflog -m "My recovered stash"

It did the trick for that person using git 2.22.0 on Ubuntu 18.04.

2. My Git client isn’t in English ​

If your Git isn’t in English, you’ll have to run alias git='LANG=en_GB git' each time you want to recover a set of stashes (thanks mathieuschopfer), otherwise the unreachable flag in git fsck --unreachable might be in another language, so you can either:

• alias the language like Mathieu (put in in your .bashrc file so it becomes permanent);
• adapt the first command: translate unreachable into your git language and update the cut command.

Advices ​

Commit messages are healthy ​

I always add a commit message to stash using git stash save -m "My commit message": without message, the only way to identify a stash are its timestamp and the branch it was saved from, which might not be enough compared to human-written words.

Commit messages also help Git clients:

• GitUp, the Git client I use, completely fails at showing unnamed stashes. That’s probably why you can’t create a stash in GitUp without giving it a name, which is great!
• The well-known SourceTree succeeds at showing unnamed stashes, but as you can guess, the list isn’t friendly to browse:

Prefer git stash apply over git stash pop ​

Unlike git stash pop, git stash apply does not remove the stash from the list of stashes, which can avoid accidental loss.

Prefer branches over stashes ​

Stashes serve a different purpose than branches. Wherever it makes sense to you, commit your code to a new branch instead of stashing it. You’re gonna start a new branch anyway if you use a branching model like Git Flow.

Setting Vitepress cleanUrls to true removes the trailing .html from URLs. The internal links of your Vitepress app changes from <a href="/something.html"> to <a href="/something">.

However, cleanUrls does not change the file names or the folder structure of the generated HTML files, which means your server must now be able to serve the /something.html file when the /something URL is requested.

Here’s how I solved it, assuming the app is hosted on its own domain or subdomain (example.tld or subdomain.example.tld, I did not test example.tld/path/to/app).

At the time of writing, I’m using Vitepress 1.0.0-rc.24 and Nginx 1.25.

Full configuration ​

If you don’t want to read the step-by-step section, here are the important parts of the configuration. Adapt them to your needs and make sure to understand the trade-off for index pages.

server {
    index index.html;
    rewrite ^(.+)/$ $1 permanent;

    if ($request_uri ~ ^/(.*)index\.html(\?|$)) {
        return 301 /$1;
    }

    if ($request_uri ~ ^/(.*)\.html(\?|$)) {
        return 301 /$1;
    }

    location / {
        error_page 404 /404.html;
        try_files $uri $uri.html $uri/ =404;
    }
}

server {
    index index.html;
    # and other things…

    # Remove the trailing slash (permanent 301 redirect). 
    rewrite ^(.+)/$ $1 permanent;

    # Remove the trailing `index.html`. 
    if ($request_uri ~ ^/(.*)index\.html(\?|$)) {
        return 301 /$1;
    }

    # Remove the trailing `.html`. 
    if ($request_uri ~ ^/(.*)\.html(\?|$)) {
        return 301 /$1;
    }

    location / {
        # When the HTTP status code is 404, answer with the `/404.html` file.
        error_page 404 /404.html;

        # When `foo/bar` (which is `$uri`) is requested, 
        # try to serve the first existing file among the list: 
        # `foo/bar`, `foo/bar.html` or `foo/bar/index.html`. 
        # Otherwise answer with a 404 code.
        try_files $uri $uri.html $uri/ =404;
    }
}

Step-by-step ​

The first step is enough to have clean URLs, the other steps after will bring refinements and safeguards.

Step 1: the gist ​

Make sure your Nginx location block have this try_files rule:

server {
    index index.html;
    # and other things…

    location / {
        # When `foo/bar` (which is `$uri`) is requested, 
        # try to serve the first existing file among the list: 
        # `foo/bar`, `foo/bar.html` or `foo/bar/index.html`. 
        # Otherwise answer with a 404 code.
        try_files $uri $uri.html $uri/ =404; 
    }
}

At this step, most paths are working with and without .html:

We need 3 improvements:

• Vitepress 404 page (see step 2) instead of Nginx 404 message;
• a fix for the 403 when there’s a trailing slash (step 3);
• no more paths with .html (step 4);

Step 2: the 404 page ​

The default Vitepress comes with a 404.html page. Let’s serve it using the error_page directive:

server {
    index index.html;
    # and other things…

    location / {
        # When the HTTP status code is 404, answer with the `/404.html` file. #
        error_page 404 /404.html; 
        try_files $uri $uri.html $uri/ =404;
    }
}

Step 3: avoiding the 403 errors ​

To avoid the 403 on paths with a trailing slash (e.g. my-blog.com/ or my-blog.com/notes/), we can redirect them to their non-trailing slash version using the rewrite directive in the server block.

server {
    index index.html;
    # and other things…
    # Remove the trailing slash (permanent 301 redirect). #
    rewrite ^(.+)/$ $1 permanent; 

    location / {
        error_page 404 /404.html;
        try_files $uri $uri.html $uri/ =404;
    }
}

Step 4: redirect /slug.html to /slug ​

For now, /slug and /slug.html are both working, so let’s redirect the one with the trailing .html.

https://stackoverflow.com/questions/38228393/nginx-remove-html-extension

server {
    # other things…

    rewrite ^(.+)/$ $1 permanent;
    # Remove the trailing `index.html`. #
    if ($request_uri ~ ^/(.*)index\.html(\?|$)) { 
        return 301 /$1; 
    } 
    # Remove the trailing `.html`. #
    if ($request_uri ~ ^/(.*)\.html(\?|$)) { 
        return 301 /$1; 
    } 

    location / {
        error_page 404 /404.html;
        try_files $uri $uri.html $uri/ =404;
    }
}

The trade-off for index pages ​

If you have index pages like notes/index.md, you have to move them to notes.md, otherwise you’ll experience an infinite redirection loop where Nginx wants to remove the slash, but Vitepress wants to add it back.

In other words, do this:

.
├─ index.md
├─ notes
│  ├─ index.md // [!code --]
│  ├─ post-1.md
│  └─ post-2.md
├─ about.md
└─ notes.md // [!code ++]

Readings ​

Aside from Nginx documentation for the HTTP core module, I was helped by:

• NGINX remove .html extension (StackOverflow)
• Routing access failure after server Nginx deployment (GitHub issue on Vitepress repository): this was where I started before deciding to write this post.