You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Jerpy is a flat-file PHP CMS built for control and simplicity that is easy to install, customize, and maintain.
5
-
**The whole templating engine is under 1700 characters of PHP code, and the data structure is only 4 directories and 2 files.**
7
+
Jerpy is one of the smallest, flat-file PHP content management systems (CMS) built for control and simplicity that is easy to installs, customize, and maintain.
6
8
7
-
This was built to be as streamlined and stripped-down as possible, so it's meant to be administered directly via the files and there's no admin web panel.
9
+
**This was built to be as streamlined and stripped-down as possible, so it's meant to be administered directly via the files and there's no admin web panel.**
8
10
9
11
# Getting Started
10
12
## Composer
11
-
Jerpy is super easy to get setup. Simply run the following to download and extract, then copy or rename `config.sample.json` to `config.json`.
13
+
Jerpy is super easy to get setup. Simply run the following to get started:
There are 3 directories for content, one directory for plugins, and one file for configuration. The `pages`, `layouts`, and `assets` directories will hold page contents, layout templates, and site assets, respectively.
18
-
19
-
## Pages
20
-
The `pages` directory stores the page contents for the site, and can be referenced as a file path on the `file` property of a route.
21
-
```
22
-
🗀 pages
23
-
🗋 home.php
24
-
```
25
-
```json
26
-
{
27
-
"routes": {
28
-
"/": {
29
-
"title": "Home",
30
-
"file": "pages/home.php"
31
-
}
32
-
}
33
-
}
34
-
```
18
+
# File/Folder Structure
19
+
## `config.php`
20
+
All site settings are set in the `config.php` file, including timezone, selected layout, enabled plugins, and page routes.
35
21
36
22
## Layouts
37
-
The `layouts` directory stores layout templates, each their own `.php` file. The default global theme is set in `config.json` on the `layout` property.
23
+
The `layouts` directory stores layout templates, each their own `.php` file. The default global theme is set in `config.php` via the `$layout` property.
38
24
```
39
25
🗀 layouts
40
26
🗋 default.php
41
27
```
42
-
```json
43
-
{
44
-
"layout": "default"
45
-
}
28
+
```php
29
+
$layout = 'default';
46
30
```
47
31
48
32
## Assets
@@ -53,110 +37,96 @@ This is the global assets directory, in which you can organize your CSS, JavaScr
Routes are defined separately from pages to easily manage the content and access of each route.
61
-
62
-
## Route Properties
63
-
Each route is defined as a key on the `routes` property in `config.json` whose value is an object with properties that define the route's page title and content.
47
+
## Pages & Routes
48
+
The `pages` directory stores the page contents for the site, and are configured for each route in `config.php`.
49
+
```
50
+
🗀 pages
51
+
🗋 home.php
52
+
```
53
+
```php
54
+
$routes = [
55
+
'/' => 'pages/home.php'
56
+
];
57
+
```
58
+
You can define a route as a key with either a string pointing to the file, or an associative array with a `page` key and other options to change how the page is rendered.
64
59
65
-
|Name|Data Type|Required?|Note|
66
-
|---|---|---|---|
67
-
|`title`|`string`|Yes|Page title|
68
-
|`file`|`string`|Conditional|Required if `body` not set. Overwrites `body` value with rendered content|
69
-
|`body`|`string`|Conditional|Required if `file` not set. Throws error if neither `file` and `body` set|
70
-
|`layout`|`string`|No|If set to valid path, will override default `layout`. If set to false, no layout is used and page body is echoed as is|
60
+
To use a different layout than the default, set the `layout` option:
61
+
```php
62
+
$routes = [
63
+
'/about' => [
64
+
'page' => 'pages/about.php',
65
+
'layout' => 'layouts/layout2.php'
66
+
]
67
+
];
68
+
```
69
+
If you don't want any layout to be used at all, set the `layout` option to `false`, which will just render the page by itself.
71
70
72
-
Additional arbitrary properties can be set for metadata/SEO purposes, but the title and file/body properties are the only necessary properties:
73
-
```json
74
-
{
75
-
"routes": {
76
-
"/": {
77
-
"title": "Page Title",
78
-
"file": "pages/page.php",
79
-
"description": "This is a description of the page for SEO",
80
-
"thumbnail": "/assets/img/seo.jpg"
81
-
}
82
-
}
83
-
}
71
+
Additional arbitrary properties can also be set for metadata/SEO purposes:
72
+
```php
73
+
$routes = [
74
+
'/about' => [
75
+
'page' => 'pages/about.php',
76
+
'title' => 'About',
77
+
'thumbnail' => '/assets/my_thumbnail.png'
78
+
]
79
+
];
84
80
```
85
81
You can then implement your additional properties in your layout, such as for social media SEO tags. Use the `@` warning suppressing syntax for when some routes don't have the property specified:
You can also specify non-static matching routes for the key string. Use the `:param` syntax to dynamically match a route and have its parameters set to the parsed values from the incoming URI:
97
-
```json
98
-
{
99
-
"routes": {
100
-
"/products/:id": {
101
-
"file": "pages/product.php"
102
-
}
103
-
}
104
-
}
105
-
```
106
94
```php
107
-
<p>ID: <?= $req->params['id'] ?></p>
95
+
$routes = [
96
+
'/products/:id' => 'pages/product.php'
97
+
];
108
98
```
109
-
110
-
# Templating
111
-
Page files are included, rendered on the buffer, and their output is assigned to `$page->body`. To include the page content in a template, simply echo the value of `$page-body`:
112
99
```php
113
-
<body>
114
-
<?= $page->body ?>
115
-
</body>
100
+
<p>ID: <?= $req->params->id ?></p>
116
101
```
117
102
118
-
Aside from page content, Jerpy relies on the built-in templating functionality of PHP, so use `include` and `require` as you would normally for everything else, parsing content as needed (see [plugins](#plugins) below).
103
+
# Templating
104
+
PHP's built-in templating is still sufficient for most user-cases nowadays. As such, just use `include` and `require` as you would normally for templating your site, parsing content as needed (see [plugins](#plugins) below).
119
105
120
106
## Global Variables
121
-
There are 4 global variables you can use in a layout or page file: `$config`, `$req`, `$page`, and `$assets`.
107
+
There are a couple of global variables you can always reference in a layout or page file: `$req`and `$page`
122
108
|Name|Data Type|Note|
123
109
|---|---|---|
124
-
|`$config`|`object`|The stdClass object of `config.json`|
125
-
|`$req`|`object`|The current request, contains properties `path` (string of URI), `method` (string of HTTP method), `query` (object of URL query parameters), and `params` (object of dynamic URI parameters)|
126
-
|`$page`|`object`|Contains the `body` content property, as well as all the properties defined by the route object|
127
-
128
-
# Config.json
129
-
```json
130
-
{
131
-
"siteName": "My Site",
132
-
"maintenance": false,
133
-
"layout": "default",
134
-
"routes": {}
135
-
}
136
-
```
137
-
|Name|Data Type|Note|
138
-
|---|---|---|
139
-
|`siteName`|`string`|Name for site|
140
-
|`maintenance`|`boolean`|Toggle site-wide maintenance mode. When true, returns HTTP 503 for all routes|
141
-
|`layout`|`string`|The default layout to use for routes|
142
-
|`routes`|`object`|Key:value object of all defined routes|
110
+
|`$req`|`object`|The current request, contains properties `uri`, `method` (HTTP Method), `query` (object of URL query parameters), and `params` (object of dynamic route parameters)|
111
+
|`$page`|`string`|Path to the page file being rendered|
143
112
144
113
# Plugins
145
-
Plugins can be made for Jerpy, but they do not follow any specific framework or design pattern. This is left up to the developer to ensure that the plugin works and tests succesfully with all the existing features of Jerpy.
146
-
147
-
The only requirements for plugins are that the entrypoint that is included globally at runtime must be a `.php` file with the same name as the plugin's folder:
114
+
Plugins can be made to extend or add functionality to Jerpy. They do not require any specific framework nor follow any particular design pattern. The only requirement for plugins is that the entrypoint is a `.php` file with the same name as the plugin's folder. From there, you can use whatever preferred tools and package managers to create the plugin code.
148
115
```
149
116
🗀 plugins
150
117
🗀 myPlugin <-- plugin dir
118
+
🗋 composer.json
151
119
🗋 myPlugin.php <-- entrypoint (same as plugin dir)
152
120
🗀 vendor
153
121
🗋 someSupportingFile.php
154
122
```
155
123
156
-
Plugins are loaded globally and their top-level objects, functions, and/or classes are made accessible in templates and pages.
124
+
Plugins are loaded globally, and their top-level objects, functions, and/or classes are accessible from all layouts and pages.
157
125
158
126
To add a plugin, simply copy/upload the plugin's folder to the `plugins` directory.
159
127
128
+
To enable a plugin, add it's folder name to the `$plugins` array in `config.php`.
129
+
160
130
Below is an example plugin for using Parsedown via a wrapper method:
161
131
162
132
`plugins/md/md.php`
@@ -165,13 +135,19 @@ Below is an example plugin for using Parsedown via a wrapper method:
165
135
166
136
require 'vendor/Parsedown.php';
167
137
168
-
function md($p)
138
+
function md(string $path): string
169
139
{
170
-
$pd = new \Parsedown();
171
-
return $pd->text(file_get_contents($p));
140
+
return (new Parsedown)->text(file_get_contents($path));
0 commit comments