~cyborg/php-blog

A simple yet effective blogging system in PHP.
add test site link
generalize the repository as a template
update post 028 and add post 035

refs

main
browse  log 

clone

read-only
https://git.sr.ht/~cyborg/php-blog
read/write
git@git.sr.ht:~cyborg/php-blog

You can also use your local clone with git send-email.

#PHP-Blog

PHP-Blog is a simple, database-free blogging web app written in PHP, with the support of Markdown and JSON.

#Philosophy

Websites, blogs included, should be able to degrade gracefully over time. For blogs, this means open-sourcing your blog and publishing articles and metadata straight to the Git repository.

This project allows you to blog and keep your articles, article metadata, and user comments within this repo. This is done through the use of JSON files to store article metadata and user comments (instead of using a database), and the use of Markdown files to store written articles.

#Example Site

Use the example website to test it out before you have to do anything yourself. Keep in mind that the CSS is extremely minimal on purpose and can be modified & expanded easily.

If you have any questions, feel free to email me at hello@cleberg.io.

#Installation

Steps:

cd yourBlog.com
git clone https://github.com/christian-cleberg/blog/

Change the global variables at the top of the index.php script:

$websiteProtocol = 'https://';
$shortDomain = 'yourBlog.com';

Remove my personal data files:

cd _data/ && rm -rf *

Add blank data files:

touch comments.json && touch metadata.json

Remove my personal posts:

cd ../posts/ && rm -rf *

Add your first post:

touch 001-your-first-post.md

For every post you add, also add the applicable JSON object in _data/metadata.json.

Finally, enable FallbackResource in your Apache .conf file or in your .htaccess file:

FallbackResource /index.php

#Project Structure

This project uses the structure show below. Continue reading for a brief description of each file/folder.

blog/
│─── .gitignore
│─── favicon.ico
│─── index.php
│─── LICENSE
│─── README.md
│
└─── _classes/
│   │─── Comment.php
│   │─── Parsedown.php
│   └─── Template.php
│   
└─── _data/
│   │─── comments.json
│   └─── metadata.json
│   
└─── _functions/
│   │─── loadJSON.php
│   │─── loadRSS.php
│   │─── parseMarkdown.php
│   └─── submitComment.php
│   
└─── _templates/
│   └───template.html
│   
└─── posts/
│   │─── 001-your-first-post.md
│   │─── ...
│   └─── 999-many-posts-later.md
│   
└─── static/
    │─── app.css
    │─── prism.css
    └─── prism.js

#File: index.php

This file is the FallbackResource for the entire directory, so non-existent folders/files requested by users will be sent to index.php for processing. This file uses a switch statement to read the request URL and direct the user to various functions.

Each function in this file will call various other functions/classes and then send the output to the template file.


#Folder: _classes

#File: Comment.php

This class allows for the creation of user comments and provides the saveComment() function to do so.

#File: Parsedown.php

This class was not created by me, it comes from erusev/parsedown. See his MIT License for licensing questions on this code.

This class provides numerous capabilities to parse Markdown files and variables to HTML.

#File: Template.php

This class allows for the creation of a final HTML page to show the user. The echoTemplate() function will replace the {} templates in the _templates/template.html file.


#Folder: _data

#File: metadata.json

Your metadata.json file will need to contain an object for each post in the post folder. If you don't add an object for your new blog post, it won't be displayed in the browser. The structure will follow this exactly:

{
  "id": "001",
  "title": "Title of Post",
  "author": "Your Name",
  "description": "A quick little description for SEO and RSS.",
  "tag": "my-category",
  "created": "2018-12-08 00:00:00",
  "modified": "2018-12-08 00:00:00",
  "link": "https:\/\/www.example.com\/post\/blog-post-name.html",
  "published": "Yes"
}
#File: comments.json

This file is updated server-side as users submit comments on posts. You can commit these changes back to your repository by making sure the server-side git repo can read & write. Then just create git commits back to your repo from there (you can even create periodic cron jobs to do this for you, if you trust it).

You will need to perform the following commands to ensure whatever 'user' is writing to the comments.json file has the proper permissions. For Apache, the user is probably www-data.

chgrp -R www-data /path/to/website/
chmod -R g+w _data/comments.json

#Folder: _functions

#File: loadJSON.php

This file contains four (4) functions that can be called to load JSON data from a local file in various ways.

#File: loadRSS.php

This file contains a single function that will grab the _data/metadata.json file and generate a complete RSS file.

#File: parseMarkdown.php

This file uses the Parsedown class to parse a posts or comments from Markdown to HTML. It also adds additional attributes to any link found in the Markdown.

#File: submitComment.php

This file uses the Comment class to create a comment and then save it to _data/comments.json.


#Folder: _templates

#File: template.html

This file is the end result template that will be shown to users, regardless of the URL they enter. The main content in the <body> and various elements in the <head> will change depending which function calls this template.


#Folder: posts

Your posts folder will contain the .md files that will comprise the body of your blog post. Formatting follows standard Markdown guidelines.


#Folder: static

This folder contains the main CSS file (app.css), as well as a pair of optional static files from PrismJS to enable syntax highlighting in any code blocks found in posts or comments.

To remove the optional files, simply delete the unwanted files and remove the following from the pageExtras parameter string in the ShowComments() and ShowPost() functions in index.php:

<link rel="stylesheet" href="/static/prism.css">
<script src="/static/prism.js"></script>