Vorab – hierbei handelt es sich um eine Fortsetzung vom Posting Bootstrap v4 manuell kompilieren. Es hat sich ein wenig was getan und wir wollen natürlich auch mit Bootstrap v5 arbeiten können 🙂

Schaut rein, lernt eine neue Community-getriebene Bibliothek kennen und stattet eure Projekte mit Bootstrap v5 aus!

Bootstrap v5

Im Januar 2018 wurde Version 4 des populären Toolkits veröffentlicht. Es folgten einige Minor Updates mit neuen Features (bis hin zu Bootstrap v4.6 im Januar 2021).

Mehr als drei Jahre später, Gestern am 5.Mai 2021, wurde nun endlich Version 5 veröffentlicht – mit umfangreichen Änderungen!

Die technisch größten Änderungen sind sicherlich der Wegfall von jQuery und die fehlende Kompatibilität zum Internet Explorer. Der IE wird (global gesehen) noch immer von etwas unter zwei Prozent der User verwendet (Quelle).

Eine weitere „inhaltliche“ Sache die mir relativ früh aufgefallen ist: Aufgrund der „RTL“ (Right-To-Left) Kompatibilität wurden überall die Wörter left und right entfernt, da diese im RTL Betrieb keinen Sinn machen. Die betroffenen Klassen wurden umbenannt mit den Worten start und end bzw. s und e.

Das bedeutet in Bootstrap v5 haben wir keine border-left oder ml-3 Klassen mehr, diese heißen nun border-start und ms-3. Ich denke an diese Änderung muss man sich am meisten gewöhnen… Ich kann mir aber vorstellen das es hier relativ schnell Updates aus der Community geben wird in Form einer zusätzlichen scss Datei, die die alten Klassennamen wiederherstellen.

Aktualisiertes Skript

Es ist bald dreieinhalb Jahre her seitdem ich den vorherigen Bootstrap Post geschrieben habe, was hat sich seitdem getan? Zum einen wird die verwendete Bibliothek leafo/scssphp seit Juni 2019 nicht mehr weiterentwickelt. Zusätzlich war packagist für einige Zeit nicht mit dem Stand von github synchron, was ebenfalls ärgerlich war.

Das hat wiederum beim kompilieren von (damals) Bootstrap 4.2 zu Problemen geführt und das vertrauen getrübt…

Die Community hat geholfen

Denn die Bibliothek leafo/scssphp wurde auf github geforked und unter dem neuen Namen scssphp/scssphp bei Packagist veröffentlicht! Seitdem gibt es wieder regelmäßige Updates und keine Probleme mehr mit Bootstrap 😉

composer req scssphp/scssphp

Die API hat sich dabei nur minimal geändert – wir müssen nur die Namespaces anpassen und die Nutzung der „Formatter“ mit „Output Styles“ tauschen :

<?php

use ScssPhp\ScssPhp\Compiler;
use ScssPhp\ScssPhp\OutputStyle;

require_once __DIR__ . '/vendor/autoload.php';

$scss = new Compiler();
$scss->setImportPaths(__DIR__ . '/scss/');
// $scss->setFormatter(\ScssPhp\ScssPhp\Formatter\Compressed::class); Deprecated!
$scss->setOutputStyle(OutputStyle::COMPRESSED);

// $compiledCss = $scss->compile(file_get_contents(__DIR__ . '/scss/build.scss')); Deprecated!

// Änderungen ab scssphp/scssphp v1.5.0:
$compiledCss = $scss
    ->compileString(file_get_contents(__DIR__ . '/scss/build.scss'))
    ->getCss();

file_put_contents(__DIR__ . '/css/my-bootstrap-min.css', $compiledCss);

Damit der Code in dieser Form funktioniert müssen wir ein wenig was auf Dateisystem-Ebene vorbereiten. Zunächst laden wir uns den Quellcode von Bootstrap v5 runter und entpacken ihn.

Im entpackten Ordner finden wir einen scss Ordner, diesen kopieren wir in unser Projekt unter einen eigenen scss ordner und benennen ihn in bootstrap-5.0.0 um (am besten entsprechend der Bootstrap Version). Die Verzeichnisstruktur sollte so aussehen:

unser-projekt/
├─ css/
├─ scss/
│ └─ bootstrap-5.0.0/
│   └─ ...
├─ vendor/
│ └─ ...
├─ composer.json
├─ composer.lock
└─ index.php

Aus dem bootstrap-5.0.0 Ordner kopieren wir die bootstrap.scss eine Ebene nach oben und benennen diese in build.scss um. Diese wird verwendet um alle Bootstrap Komponenten in der korrekten Reihenfolge zu importieren – doch wir müssen die Datei etwas anpassen, weil wir uns in einer anderen Ordner-Ebene befinden.

Wir müssen überall den bootstrap-5.0.0 Ordner hinzufügen, damit der Import die korrekte Datei findet – das sollte in etwa so aussehen:

/*!
 * Bootstrap v5.0.0 (https://getbootstrap.com/)
 * Copyright 2011-2021 The Bootstrap Authors
 * Copyright 2011-2021 Twitter, Inc.
 * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
 */

// scss-docs-start import-stack
// Configuration
@import "bootstrap-5.0.0/functions";
@import "bootstrap-5.0.0/variables";
@import "bootstrap-5.0.0/mixins";
@import "bootstrap-5.0.0/utilities";

// Layout & components
@import "bootstrap-5.0.0/root";
@import "bootstrap-5.0.0/reboot";
...

Dies ist auch gleichzeitig die Stelle an der wir Komponenten auskommentieren können, die wir in unserem Projekt nicht benötigen. Das sorgt dann natürlich auch für eine kleinere kompilierte CSS Datei 🙂

Andererseits wäre dies auch die Stelle um eigene Variablen zu setzen (ganz am Anfang, vor dem Import von bootstrap-5.0.0/variables) oder eigene Styles anzuhängen (ganz am Ende).

Durch die angepasste Struktur im Dateisystem ist das Skript auch um ein paar Zeilen kürzer geworden. Wir benötigen nicht mehrere „Import Pfade“ und auch die Ausgabe schreiben wir ganz simpel in den css Ordner.

CSS Kompilieren

Nachdem wir das Skript erzeugt, die SCSS Dateien kopiert und unsere eigene build.scss erstellt haben können wir theoretisch loslegen und Bootstrap selbst kompilieren – dazu einfach den PHP Code ausführen, z.B. auf der Konsole via php index.php.

Nach ein paar Sekunden sollte im css Ordner eine neue Datei auftauchen mit dem Namen my-bootstrap-min.css – das war’s!

Richtig interessant wird es nun wenn ihr eine eigene variables.scss Datei erstellt und beginnt Bootstrap komplett nach euren Wünschen zu gestalten.

Mehr Optionen?

Wie vorhin kurz beschrieben wurde die „Formatter“ Logik gegen „Output Styles“ ausgetauscht, hierbei gibt es leider nur noch zwei Optionen (statt wie früher vier), siehe OutputStyle::EXPANDED und OutputStyle::COMPRESSED. Die Formatter wurden aufgrund der Kompatibilität zu dart-sass gestrichen.

Wir könnten auch an den Anfang des kompilierten CSS den Zeitpunkt der Kompilierung schreiben:

<?php

$prefix = '/* Compiled at ' . date('Y-m-d H:i:s') . ' */' . PHP_EOL;

// $compiledCss = $scss->compile(file_get_contents(__DIR__ . '/scss/build.scss')); Deprecated!

// Änderungen ab scssphp/scssphp v1.5.0:
$compiledCss = $scss
    ->compileString(file_get_contents(__DIR__ . '/scss/build.scss'))
    ->getCss();

file_put_contents(__DIR__ . '/css/my-bootstrap-min.css', $prefix . $compiledCss);

Von dieser Kleinigkeit abgesehen kann ich mir nicht vorstellen was man noch für Optionen benötigen könnte – im PHP Code sind wir natürlich frei alles zu tun was wir möchten.

Der Ziel dieses Beitrags soll auch hauptsächlich sein den alten Beitrag zu aktualisieren und abzulösen 🙂

Ich hoffe das kleine Skript hilft euch weiter und ihr könnt eure Projekte mit Bootstrap 5 ausstatten! Ich wünsche euch viel Spaß und Erfolg und bis zum nächsten Mal natürlich…
Happy Coding!

Update – falls ihr von Bootstrap v4 auf v5 wechselt schaut euch unbedingt die „Migration to v5“ Seite an!

Update 2 – Knapp eine Woche nach der Veröffentlichung wurde bereits Bootstrap v5.0.1 veröffentlicht 🙂

Update 3 – Hallo zusammen, am 14.Mai wurde scssphp/scssphp in der Version 1.5.0 veröffentlicht. Leider gibt es hier sowohl Änderungen an der API der Bibliothek als auch Probleme mit Bootstrap v5 🙁 Ich würde daher empfehlen die Version 1.4 zu nutzen.

Update 4 – Dank der Community wurde Heute scssphp/scssphp Version 1.5.1 veröffentlicht 🙂 Mit dieser Version lässt sich Bootstrap v5 wieder kompilieren.

Bitte achtet darauf, das die Methode $scss->compile(' ... ') nun „deprecated“ ist. Stattdessen muss $scss->compileString(' ... ')->getCss() verwendet werden.