PHP製の静的サイトジェネレーター「Sculpin」の紹介と使い方の解説

本記事では、PHP製の静的サイトジェネレーター(Static Site Generator)の 「Sculpin」について解説をしていく。

公式サイト：Sculpin — PHP Static Site Generator

Sculpinの特徴とは

Sculpinとは、PHP製の静的サイトジェネレーターであり、 主にSymfony製のライブラリによって作られた静的サイトジェネレーターである。

静的サイトジェネレーターはPHP以外にも様々な言語で実装されており、特に以下の静的サイトジェネレーターが人気を得ている。

• Go製のHugo
• JavaScript製のNext.js Gatsby
• Ruby製のJekyll

「Static Site Generators - Top Open Source SSGs | Jamstack」のページでも詳しく紹介されているが、2022年2月時点で静的サイトジェネレーターは333つ存在している。

そんな中、HugoやJekyllにインスパイアされて登場したのが、我らがPHP製のSculpinと言うわけだ。

他の静的サイトジェネレーターと比較してのSculpinの優位性とは

正直に言うと、他の静的サイトジェネレーターと比較してSculpinの優位点はない。

そもそも、静的サイトジェネレーターは

• 1, markdownで記事を書いて、HTMLでテンプレートを作成
• 2, 1で作ったものを元に、主に文字列処理を行う
• 3, 最終的に完成したHTMLファイルを出力

と言う仕組みになっているので、FileIOや文字列処理が得意な言語ほど向いている傾向がある。

そこで並行処理が得意なGoが、静的サイトジェネレーターに向いている。

また、結局の所、静的サイトの主役はCSSやJavaScript等のフロントエンドなので、 フロントエンドとの親和性が高いJavaScript製の静的サイトジェネレーターが望ましい。

それにSculpinはJekyllやHugo等の超人気ジェネレーターと比較すると、テンプレートやライブラリが 少ないのも欠点となっている。

つまり、SculpinはPHPを愛し、PHPのためなら死ねるPHPer向けの静的サイトジェネレーターと言える。

2022年現在のSculpinのコミュニティの状況

2022年現在でもSculpinのコミュニティはそれなりに盛り上げを見せており、 継続的に開発は続けられている。

最新版は2021年6月にリリースされた3.1.1なので、今からSculpinを始めても遅くない。

「A discussion on the next steps for Sculpin · Issue #451 · sculpin/sculpin」のIssueでも 「これからSculpinをどうやって発展させていくか」の議論もされており、 個人的にはLiveEditor機能が実装されるのが楽しみ。

Sculpinの使い方

以下は、Sculpinでの静的サイトの作り方を解説していく。

Sculpinを動かす前に以下のものを事前に用意しておくこと。

• Composer
• Node.js

Sculpinでは、フロントエンドはsymfony/webpack-encoreと言うビルドツールを使って、 サーバーにデプロイするJavaScriptやCSSを生成する。

symfony/webpack-encoreは、設定ファイルが複雑になりやすいWebpackをシンプルに使うためのツールで、 Webpackのラッパーツールとなっている。

Sculpinで静的サイトを作る

Sculpinは静的サイトのひな形となるテンプレートをいくつか用意してくれている。

• sculpin/sculpin-blog-skeleton: A skeleton for a Sculpin based blog.
• sculpin/bootstrap-3-blog-theme: A Bootstrap 3 Blog Theme for Sculpin
• beryllium/sculpin-tailwind-blog-skeleton: A skeleton Sculpin Blog using Tailwind

今回は、最もオーソドックスなsculpin/sculpin-blog-skeletonを使って解説をしていく。

まずは以下のコマンドを実行すると、my-blogディレクトリにSculpinのひな形が作成される。

composer create-project -s dev sculpin/blog-skeleton my-blog

my-blogディレクトリ配下には、既にcomposer.jsonやpackage.json、webpack.config.js が用意されているので、以下のコマンドを実行する。

cd my-blog
composer require
npm install

そして最後に、以下のコマンドを実行。

composer run sculpin-watch

これでhttp://localhost:8000にアクセスをすると、ブログが生成されている。

Sculpinでは、開発環境はoutput_dev、本番環境はoutput_prodディレクトリ配下に 静的ファイルが出力されるようになっている。

本番環境用の静的ページを生成したい場合は、以下のコマンドを実行すればよい。

vendor/bin/sculpin generate --env=prod

Sculpinをカスタマイズする

以下は、Sculpinのカスタマイズ方法を解説していく。 解説は先ほどのsculpin/sculpin-blog-skeletonを使う事を前提に進めていく。

現在のトップディレクトリ配下には、以下のディレクトリがあるはずだ。

• app/config/
• source/

まずはsource/ディレクトリから解説する

source/ ディレクトリ

静的サイトを作る根幹となるディレクトリ。 基本的にsourceディレクトリ配下にあるファイル、ディレクトリは最終的に静的ページとして出力される。

例えば、source/about.mdのファイルを見てみよう。

---
layout: default
title: About

---
# About the Author or Blog

Here is a little information about the author or the blog.

---で囲まれている部分はコンテンツのmeta情報で、---以下がコンテンツの本文となる。

lauout: defaultと書かれているが、これは「source/_layouts/default.htmlのテンプレートを元に静的ページを作成しますよ」 と指定している。

実際にsource/_layouts/default.htmlを見てみると、テンプレートであることが分かる。

このdefault.htmlに書かれている{{ page.title }}にabout.mdの記事タイトル、 {% block content %}{% endblock %} に記事本文が挿入されて、最終的にoutput_dev/about.htmlの静的ページとして出力される。

source配下の特別なディレクトリ

先述した様に、source配下のファイル、ディレクトリは全て静的ページとして出力される。

しかし、以下のディレクトリは特別で、 主にabout.mdの様なMarkdownファイルや、後述するpaginationやcategory,tagページを生成するためのテンプレート の役割をする。

• _layouts
• _partials
• _views
• _includes

Sculpinは静的ページを作る際に、この4つのディレクトリの中から指定されたテンプレートを探す。

SculpinはテンプレートのパーサーとしてTwigを利用しているので、_layouts/default.htmlの中で {{ include("header") }}の記述があると、4つのディレクトリの中から header.htmlを探してテンプレートに組み込んでくれる。

また、テンプレートの拡張子としてはhtmlだけでなく、'', 'twig', 'html', 'html.twig', 'twig.html' が使える。つまり、default.htmlをdefault.twigに書き直しても同じように動く。

source/_postsディレクトリの役割

source/_postsには、実際のブログ記事の元となるmarkdownファイルが入っている。 markdownファイルのファイル名は、sculpin.mdとすることで最終的にoutput_dev/sculpin/index.htmlと 出力される。

ファイル名の先頭に2022-01-29-sculpin.mdと日付を入れることで、ブログ記事に日付情報を入れることができる。 (静的ページになる際にはoutput_dev/sculpin/index.htmlで出力される。)

日付情報はdefault.html等のテンプレートで{{ page.date|date("Y-m-d") }}のように使う事ができる。

source/_postsにあるmarkdownファイルは、source/_views/post.htmlをテンプレートとして静的ページに生成される。

また、ブログ記事のURL等はapp/config/sculpin_kernel.ymlから変更ができる。

sculpin_content_types:
    posts:
        type: path
        path: _projects
        singular_name: project
        layout: project
        permalink: :year/:month/:day/:basename
        taxonomies:
            - categories

pathはブログ記事を入れているディレクトリを指定する。デフォルトでは、source/_postsだが、source/_projectsに変更ができる。また、pathは複数指定できる。

singular_nameは、ブログ記事を静的ページに生成する際のテンプレートを指定する。デフォルトではpost.htmlだが、 project.htmlに変更できる。

permalinkは最終的に静的ページに生成される時のURLを決められる。上記の設定だと2022/01/29/sculpin/index.htmlとして 出力される。

詳細は公式ドキュメントに記載されている。

• Posts — Sculpin — PHP Static Site Generator
• Custom Types — Sculpin — PHP Static Site Generator

paginationを作る

Sculpinでは、標準機能によって簡単にpaginationが作れる。

source/index.htmlを見ると、以下の様に書かれている。

---
layout: default
title: Home
generator: pagination
pagination:
    max_per_page: 3
use:
    - posts
---

テンプレートにgenerator: paginationと書くことで、簡単にpaginationを作成できる。 また、max_per_page: 3の数字を変更することで、1ページ毎の記事数を変更できる。

source/index.htmlの場合だと、1ページはoutput_dev/index.html、2ページ目以降は output_dev/page/2/index.htmlとして出力される。

Categoryページを作成する

Categoryページを作成するのも簡単で、source/blog/categories/category.htmlを見てみよう。

---
layout: default
title: Category Archive
generator: [posts_category_index, pagination]
pagination:
    provider: page.category_posts

---

先ほどのindex.htmlと違うのはgenerator: [posts_category_index, pagination]と記述されていること。 posts_category_indexと指定して上げることで、category毎の記事を集めてくれる。

app/config配下の役割

app/config配下のファイルは、以下の2種類のファイルが用意されている。

• sculpin_kernel.yml
• sculpin_site.yml

sculpin_kernel.ymlは先ほどのsource/_postsの設定で行ったように、Sculpinの静的ページの作り方を 指定するための設定ファイルになる。

先ほどの例で言えば、ブログ記事を入れるディレクトリをsource/_projectsに変更したはずだ。

逆にsculpin_site.ymlは、テンプレート内で使う変数を設定するためのもの。

例えば、sculpin_site.ymlに以下の記載をしたとする。

title: Sculpin Blog Skeleton
subtitle: To Get You Started

すると、source/_layouts/default.htmlやsource/_views/post.html等の テンプレート内で{{ site.title }}と書くことができる。

また、sculpin_site_prod.ymlやsculpin_site_dev.ymlの様に環境ごとに設定ファイルを変更する事もできる。

参考になる記事、サイト

Sculpinを使う時に参考になる記事、サイトを上げていく。

• Documentation — Sculpin 公式ドキュメント。大体ここに知りたいことが載っている。
• sculpin/sculpin: 公式リポジトリ。ドキュメントを読んでも分からない場合はコードを読むしかない。

私も色々ネットを漁ったが、Sculpinについての情報は日本語・英語問わずほとんどない。 なので、基本的に「ドキュメント読め。分からん場合はコードを読め」となる。

もし、あなたが単に静的サイトで技術ブログを作りたい場合は、Sculpinではなく、HugoやJekyll等の コミュニティがより活発な静的サイトジェネレーターを使った方が幸せになれるだろう。

仮にあなたが「どうしてもPHPの静的サイトジェネレーターを使いたい」と言う狂信的なPHPerであれば、 Sculpinは良い遊び道具になってくれる。