Laravel Bjyblog Laravel Package

Getting Started

This is a complete Laravel 9 application, not a Composer library — you do not composer require it. You fork or clone it and treat the codebase as your own.

git clone https://github.com/baijunyao/laravel-bjyblog.git my-blog
cd my-blog
composer install
cp .env.example .env
php artisan key:generate

Configure .env (MySQL/MariaDB with utf8mb4 is the safe choice), then:

php artisan migrate --seed
php artisan storage:link
npm install && npm run build   # check whether the branch uses Vite or Mix
php artisan serve

Where to look first:

• routes/web.php and the admin route file (usually routes/admin.php or registered in RouteServiceProvider) — this reveals the frontend vs. /admin split.
• app/Http/Controllers/Admin/ — the CRUD pattern you will copy for any new content type.
• database/seeders/ — admin account credentials are seeded here; change the password immediately after first login.
• config/ — check for a project-specific config file (e.g. bjyblog.php) for site name, upload paths, and behavior toggles.
• resources/views/ — separate admin/ and frontend theme trees.

First use case: log in at /admin with the seeded credentials, publish one article with a category and tags, then confirm it renders on the frontend. This exercises the full write path (auth → controller → model → sitemap/cache hooks → public view) before you customize anything.

Implementation Patterns

Copy the Article module for new entities. The Article flow (migration → Model → Admin resource controller → Blade create/edit forms → frontend presenter) is the canonical template. When adding something like "Series" or "Projects," clone those files structurally rather than inventing a new pattern; it keeps the admin navigation, validation, and listing conventions consistent.

Respect the admin/frontend split. Keep admin controllers in the Admin namespace and behind the package's auth guard/middleware. Frontend controllers should stay thin — read models, pass to Blade, done. Mixing concerns here is the fastest way to make upgrades painful.

Use model scopes for visibility. Publish/draft state should be a query scope (e.g. published()), applied consistently in frontend controllers, widgets, and sitemap generation. Never filter inline in views — it will drift.

Hook caching and sitemap regeneration to model events. Register Observer or model event listeners in a service provider for save/delete on Article to bust the cache and rebuild the sitemap. This is the intended extension point rather than sprinkling logic in controllers.

Extend via Blade composition. Frontend themes are Blade layouts plus partials. Add widgets as Blade components or includes rather than editing core layout files, so you can swap themes without conflicts.

Add admin menu entries in one place. The admin sidebar is typically driven by config or a single Blade partial — add new modules there so navigation stays consistent.

Handle uploads through the existing storage abstraction. Article cover images and attachments already have a convention; reuse that disk/path helper instead of hardcoding public_path(), otherwise storage:link assumptions break.

If search is wired up (Scout/Elasticsearch), keep the index in sync via observers, not manual reindex calls in controllers.

Gotchas and Tips

• Treat upgrades as manual diffs, not composer update. Since this is an app, upstream changes must be pulled and merged by hand. Tag your fork and diff against upstream releases deliberately.
• Documentation and inline comments are largely in Chinese. Machine translation is fine for config comments, but read model relations and migration ordering carefully before editing — subtle meaning loss is common.
• Change seeded admin credentials and the APP_KEY before exposing anything. Default seeders are the single most common source of compromised deployments.
• MySQL charset matters. Use utf8mb4 in both the database and the connection config, or emoji and CJK content in comments will truncate or error.
• Timezone and locale default to the original author's region. Check config/app.php timezone and locale — scheduled posts and displayed dates will be wrong if left as-is.
• Comment spam is real. Plan for moderation and either captcha or rate limiting on the comment endpoint from day one; the moderation UI exists but does not stop submission spam.
• Storage permissions bite on shared hosting. Ensure storage/ and bootstrap/cache/ are writable and that storage:link succeeded; failed cover images are almost always a symlink or permission issue, not a code bug.
• Confirm the asset pipeline before styling work. Different releases/tags used Mix vs. Vite. Editing the wrong build config wastes an afternoon — check package.json scripts and vite.config.js/webpack.mix.js presence.
• Cache driver matters at scale. Switch to Redis for sessions and cache before launch; file-based caching plus sitemap regeneration on every save gets slow with a few thousand posts.
• Sitemap and RSS are generated artifacts. If you write posts via the API or a seeder rather than the admin UI, observers may not fire — trigger regeneration manually in that path.
• No first-class i18n. If you need a multilingual blog, plan a separate strategy (per-locale routes and content columns) rather than expecting built-in support.
• Extension points to prefer: service providers for bindings and event registration, observers for cross-cutting side effects, Blade components for widgets, and config files for toggles. Avoid editing vendor-style core files; leave those for genuine bug fixes so upstream merges stay tractable.