This package is a flexible blogging solution that you can add to your Laravel app.
Is takes blog entries from storage and publishes them to the Web in common formats for consumption by people and machines through URLs.
Each blog gets:
The default storage is Eloquent,
but you can write your own BlogEntryProvider
should you wish.
Have a look at the files in
src/Contracts
for a quick overview of the entites this package handles.
This package does not provide any admin interface for editing blog entries. There's a separate package that can optionally be installed to provide admin routes for editing blog contents.
Another option is to create the mechanism to edit blog entries yourself, in your Laravel app. Entries are represented by Eloquent models by default, so shouldn't be too hard for Laravel developers.
You need at least Laravel 5.6.8 to use this package. The included entry model and migration requires a database connection supporting json-type columns.
Require the package:
composer require bjuppa/laravel-blog
The package will automatically register itself.
Publish the configuration file:
php artisan vendor:publish --provider="Bjuppa\LaravelBlog\BlogServiceProvider" --tag="blog-config"
Edit the published configuration file config/blog.php
to setup your desired blogs and their options.
Configurations may be changed later and more blogs can be added etc. Just remember that permalinks and generated entry IDs should ideally be kept constant after a blog has been published to avoid broken feeds and links for your audience.
The service provider handles registration of routes to all configured blogs. You can check which routes and paths are generated using:
php artisan route:list
Run migrations to automatically set up any tables needed to use the configured blog entry providers:
php artisan migrate
(optional) If you want to create a default blog entry in the database you can run the seeder:
php artisan db:seed --class="Bjuppa\LaravelBlog\Database\Seeds\DefaultBlogEntrySeeder"
(optional) If you want to use the included styling, first publish the CSS to your public directory:
php artisan vendor:publish --provider="Bjuppa\LaravelBlog\BlogServiceProvider" --tag="blog-styling"
...then edit config/blog.php
and add 'css/blog.css'
to the stylesheets
config.
Now visit your fresh blog in a browser!
The default url path is /blog
unless you've changed the config.
Add and edit blog entries in the database any way you like.
You can create your own admin interface, write straight to the database,
or perhaps use
php artisan tinker
... 😉
The model used by default is
Bjuppa\LaravelBlog\Eloquent\BlogEntry
.
There is a separate package providing an admin interface.
All published entries are public to view by anyone at their url.
To enable users to preview unpublished entries, first create a Laravel
gate or
policy
(for your entry model) and then configure the preview_ability
in your
config/blog.php
to match.
A gate defined in your App\Providers\AuthServiceProvider
could look like this:
Gate::define('preview blog entries', function ($user) {
// Check for your own admin user model, or some other criteria!
return $user instanceof \App\AdminUser;
});
The included CSS file is built using Kingdom CSS, which is yet another CSS framework, created by... yours truly.
The default styling is meant to add some consistent styling to the standard HTML elements, so a blog using it will not look "designed", although it has some opinionated layout and spacing (especially on a larger screen). You could say it has a "brutalist" approach, it even uses browsers' default fonts.
Blog authors may want to add some special styles to elements within their entries. Some classes are useful on elements that are on the first level within entry contents:
.full-bleed
will expand the element to cover the entire width
of the viewport - great for images..start-margin-bleed
and .end-margin-bleed
will make the element extend
into the left or right margin..float-right
and .float-left
will float the element in single-column view..span-content
will make the element cover both columns when the screen is
big enough for a two-column view - good for elements that require more
space, but not the full width..full-column-bleed
is similar to .full-bleed
but will not
cover multiple columns..blog-related-content
will move the the element into the first available
row of the second column - great for <aside>
elements and other
content that is related to the entry, but doesn't need to
follow exactly in the flow.
(The ads section is an example of this, that goes into the first free slot of the second column)
If your related content needs to cover more than one row in the second column,
you can add utility classes .grid-row-span-2
, .grid-row-span-3
,
etc (from Kingdom).
The included CSS contains many of Kingdom's utility classes, they're too many to document here, please refer to the original SASS files:
_colors.scss
_borders.scss
_sizing.scss
_spacing.scss
layout/_lists.scss
layout/_screenreaders.scss
layout/_floats.scss
layout/_grid.scss
text/_whitespace-wrapping.scss
You probably want to create your own styles to apply your personal
touch or branding.
The stylesheets
config in your config/blog.php
is where you can include
any CSS files you want into your blog.
You can add a list of files so you can combine this package's CSS file with an additional CSS file containing your own styles. Or you can use Laravel Mix to combine them into a single file.
If you're feeling adventurous, pull in the
Kingdom npm
package
and use it in your build.
You may draw inspiration from, or even include,
the SASS files from this package.
The package keeps all its Blade views in
resources/views
and running this command will publish all of them into
resources/views/vendor/blog
of your app so you can edit them:
php artisan vendor:publish --provider="Bjuppa\LaravelBlog\BlogServiceProvider" --tag="blog-views"
...however you probably only need to change a few bits in just some files.
I'd recommend you to only commit the files you actually change to version
control, and remove the rest of the published files that you have not
changed from your app.
Blade will fall back to using the package's views for any file not found in
the vendor
view directory.
This package contains English translation strings that can be published to your app using this command:
php artisan vendor:publish --provider="Bjuppa\LaravelBlog\BlogServiceProvider" --tag="blog-translations"
If you're not adding translations for a new language, you probably don't need all the files and not even all the strings within a file. Consider overriding just the ones you want, as explained in the Laravel documentation.
It is possible to pull out any configured Blog
from the BlogRegistry
within
the boot()
method of any Laravel service provider, and manipulate it beyond
what is possible using the configuration files alone.
To use a custom BlogEntryProvider
one can set it on an individual
Blog
using withEntryProvider()
.
To just use a custom entry model with a Blog
one can use
getEntryProvider()->withEntryModel()
,
as long as the entry provider is a
Bjuppa\LaravelBlog\Eloquent\BlogEntryProvider
.
When looking for ways to add a simple blog to an existing Laravel app I found many packages and some complete Laravel apps, but none of them did what I expected:
Provide a highly configurable blog add-on that can be integrated into any Laravel app.
Povilas Korop had written a blog post about it some half a year before I ran into the same need. This package is my attempt at getting myself a couple of blogs without resorting to WordPress and hopefully provide something useful for other developers.