├── .php-cs-fixer.php ├── LICENSE ├── README.md ├── assets ├── config.php └── views │ └── _markdown.blade.php ├── composer.json └── src ├── Page.php ├── PageController.php └── PagesServiceProvider.php /.php-cs-fixer.php: -------------------------------------------------------------------------------- 1 | ['syntax' => 'short'], 8 | 'binary_operator_spaces' => [ 9 | 'default' => 'single_space', 10 | 'operators' => [ 11 | '=>' => null, 12 | '|' => 'no_space', 13 | ] 14 | ], 15 | 'blank_line_after_namespace' => true, 16 | 'blank_line_after_opening_tag' => true, 17 | 'no_superfluous_phpdoc_tags' => true, 18 | 'blank_line_before_statement' => [ 19 | 'statements' => ['return'] 20 | ], 21 | 'braces' => true, 22 | 'cast_spaces' => true, 23 | 'class_definition' => true, 24 | 'concat_space' => [ 25 | 'spacing' => 'one' 26 | ], 27 | 'declare_equal_normalize' => true, 28 | 'elseif' => true, 29 | 'encoding' => true, 30 | 'full_opening_tag' => true, 31 | 'declare_strict_types' => true, 32 | 'fully_qualified_strict_types' => true, // added by Shift 33 | 'function_declaration' => true, 34 | 'function_typehint_space' => true, 35 | 'heredoc_to_nowdoc' => true, 36 | 'include' => true, 37 | 'increment_style' => ['style' => 'post'], 38 | 'indentation_type' => true, 39 | 'linebreak_after_opening_tag' => true, 40 | 'line_ending' => true, 41 | 'lowercase_cast' => true, 42 | 'constant_case' => true, 43 | 'lowercase_keywords' => true, 44 | 'lowercase_static_reference' => true, // added from Symfony 45 | 'magic_method_casing' => true, // added from Symfony 46 | 'magic_constant_casing' => true, 47 | 'method_argument_space' => true, 48 | 'native_function_casing' => true, 49 | 'no_alias_functions' => true, 50 | 'no_extra_blank_lines' => [ 51 | 'tokens' => [ 52 | 'extra', 53 | 'throw', 54 | 'use', 55 | 'use_trait', 56 | ] 57 | ], 58 | 'no_blank_lines_after_class_opening' => true, 59 | 'no_blank_lines_after_phpdoc' => true, 60 | 'no_closing_tag' => true, 61 | 'no_empty_phpdoc' => true, 62 | 'no_empty_statement' => true, 63 | 'no_leading_import_slash' => true, 64 | 'no_leading_namespace_whitespace' => true, 65 | 'no_mixed_echo_print' => [ 66 | 'use' => 'echo' 67 | ], 68 | 'no_multiline_whitespace_around_double_arrow' => true, 69 | 'multiline_whitespace_before_semicolons' => [ 70 | 'strategy' => 'no_multi_line' 71 | ], 72 | 'no_short_bool_cast' => true, 73 | 'no_singleline_whitespace_before_semicolons' => true, 74 | 'no_spaces_after_function_name' => true, 75 | 'no_spaces_around_offset' => true, 76 | 'no_spaces_inside_parenthesis' => true, 77 | 'no_trailing_comma_in_list_call' => true, 78 | 'no_trailing_comma_in_singleline_array' => true, 79 | 'no_trailing_whitespace' => true, 80 | 'no_trailing_whitespace_in_comment' => true, 81 | 'no_unneeded_control_parentheses' => true, 82 | 'no_unreachable_default_argument_value' => true, 83 | 'no_useless_return' => true, 84 | 'no_whitespace_before_comma_in_array' => true, 85 | 'no_whitespace_in_blank_line' => true, 86 | 'normalize_index_brace' => true, 87 | 'not_operator_with_successor_space' => true, 88 | 'object_operator_without_whitespace' => true, 89 | 'ordered_imports' => ['sort_algorithm' => 'alpha'], 90 | 'phpdoc_indent' => true, 91 | 'general_phpdoc_tag_rename' => true, 92 | 'phpdoc_no_access' => true, 93 | 'phpdoc_no_package' => true, 94 | 'phpdoc_no_useless_inheritdoc' => true, 95 | 'phpdoc_scalar' => true, 96 | 'phpdoc_single_line_var_spacing' => true, 97 | 'phpdoc_summary' => true, 98 | 'phpdoc_to_comment' => false, 99 | 'phpdoc_trim' => true, 100 | 'phpdoc_types' => true, 101 | 'phpdoc_var_without_name' => true, 102 | 'psr_autoloading' => true, 103 | 'self_accessor' => true, 104 | 'short_scalar_cast' => true, 105 | 'simplified_null_return' => false, // disabled by Shift 106 | 'single_blank_line_at_eof' => true, 107 | 'single_blank_line_before_namespace' => true, 108 | 'single_class_element_per_statement' => true, 109 | 'single_import_per_statement' => true, 110 | 'single_line_after_imports' => true, 111 | 'no_unused_imports' => true, 112 | 'single_line_comment_style' => [ 113 | 'comment_types' => ['hash'] 114 | ], 115 | 'single_quote' => true, 116 | 'space_after_semicolon' => true, 117 | 'standardize_not_equals' => true, 118 | 'switch_case_semicolon_to_colon' => true, 119 | 'switch_case_space' => true, 120 | 'ternary_operator_spaces' => true, 121 | 'trailing_comma_in_multiline' => true, 122 | 'trim_array_spaces' => true, 123 | 'unary_operator_spaces' => true, 124 | 'whitespace_after_comma_in_array' => true, 125 | ]; 126 | 127 | $project_path = getcwd(); 128 | $finder = Finder::create() 129 | ->in([ 130 | $project_path . '/src', 131 | ]) 132 | ->name('*.php') 133 | ->notName('*.blade.php') 134 | ->ignoreDotFiles(true) 135 | ->ignoreVCS(true); 136 | 137 | return (new Config()) 138 | ->setFinder($finder) 139 | ->setRules($rules) 140 | ->setRiskyAllowed(true) 141 | ->setUsingCache(true); 142 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 ArchTech Development, Inc. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Laravel Pages 2 | 3 | This package lets you create pages using Markdown or Blade without having to worry about creating routes or controllers yourself. 4 | 5 | Essentially, you create either `content/pages/foo.md` or `resources/views/pages/foo.blade.php` and the page will be accessible on the `/foo` route. 6 | 7 | Markdown files use a pre-defined Blade view to get rendered. Blade files are meant for pages which don't follow the default layout and need more custom styling. 8 | 9 | For instance, you could have the `/pricing` route use a Blade file (`pages/pricing.blade.php`) with a pretty design that accompanies your pricing copy. 10 | 11 | Whereas for `/about`, you could have a simple Markdown file (`content/pages/about.md`) that describes your service using pure text without any special graphical elements. 12 | 13 | We use this on the ArchTech website — the [About](https://archte.ch/about), [Careers](https://archte.ch/careers), and [Open Source](https://archte.ch/open-source) pages are simple Markdown files. 14 | 15 | ## Installation 16 | 17 | Require the package via composer: 18 | 19 | ``` 20 | composer require archtechx/laravel-pages 21 | ``` 22 | 23 | Publish the config file: 24 | 25 | ``` 26 | php artisan vendor:publish --tag=archtech-pages-config 27 | ``` 28 | 29 | And finally, add this line to the **end** of your `routes/web.php` file: 30 | 31 | ```php 32 | ArchTech\Pages\Page::routes(); 33 | ``` 34 | 35 | This line will register the routes in a way that ensures that your routes take precedence, and the page route is only used as the final option. 36 | 37 | **Important: Before attempting to visit URLs managed by this package, make sure that you configure it to use the correct layout (see the section below). Otherwise you might get an error saying that the view cannot be found.** 38 | 39 | ## Usage 40 | 41 | ### Markdown pages 42 | 43 | To create a markdown file, create a file in `content/pages/`. The route to the page will match the file name (without `.md`). 44 | 45 | For example, to create the `/about` page, create `content/pages/about.md` with this content: 46 | 47 | ```md 48 | --- 49 | slug: about 50 | title: 'About us' 51 | updated_at: 2021-05-19T19:09:02+00:00 52 | created_at: 2021-05-19T19:09:02+00:00 53 | --- 54 | 55 | We are a web development agency that specializes in ... 56 | ``` 57 | 58 | ### Blade pages 59 | 60 | To create a Blade page, create a file in `resources/views/pages/`. Like in the Markdown example, the route to the page will match the file name without the extension. 61 | 62 | Therefore to create the `/about` page, you'd create `resources/views/pages/about.blade.php`: 63 | 64 | ```html 65 | 66 | This view can use any layouts or markup. 67 | 68 | ``` 69 | 70 | ## Configuration 71 | 72 | You'll likely want to configure a few things, most likely the used layout. 73 | 74 | To do that, simply modify `config/pages.php`. 75 | 76 | The config file lets you change: 77 | - the used model 78 | - the used controller 79 | - the layout used by the markdown views 80 | - the view file used to render Markdown pages 81 | - routing details 82 | 83 | The layout is used *by* the vendor (package-provided) Markdown view. You'll likely want to set it to something like `app-layout` or `layouts.app`. 84 | 85 | If you'd like to change the file that renders the Markdown itself, create `resources/views/pages/_markdown.blade.php` (the `_` prefix is important as it prevents direct visits) and change the `pages.views.markdown` config key to `pages._markdown`. 86 | 87 | And if you'd like to customize the routing logic more than the config file allows you, simply register the route yourself (instead of calling `Page::routes()`): 88 | 89 | ```php 90 | Route::get('/{page}', ArchTech\Pages\PageController::class); 91 | ``` 92 | 93 | ## Ecosystem support 94 | 95 | The package perfectly supports other tools in the ecosystem, such as [Laravel Nova](https://nova.laravel.com) or [Lean Admin](https://lean-admin.dev). 96 | 97 | For example, in Laravel Nova you could create a resource for the package-provided `Page` model (`ArchTech\Pages\Page`) and use the following field schema: 98 | 99 | ```php 100 | public function fields(Request $request) 101 | { 102 | return [ 103 | Text::make('slug'), 104 | Text::make('title'), 105 | Markdown::make('content'), 106 | ]; 107 | } 108 | ``` 109 | 110 | ## Git integration & Orbit 111 | 112 | This package uses [Orbit](https://github.com/ryangjchandler/orbit) under the hood — to manage the Markdown files as Eloquent models. If you'd like to customize some things related to that logic, take a look at the Orbit documentation. 113 | 114 | The package also uses another package of ours, [Laravel SEO](https://github.com/archtechx/laravel-seo), to provide meta tag support for Markdown pages. We recommended that you use this package yourself, since it will make handling meta tags as easy as adding the following line to your layout's `` section: 115 | 116 | ```html 117 | 118 | ``` 119 | 120 | ## Password-protected routes 121 | 122 | The package also lets you protect certain routes with passwords. To add a password to a page, simply specify the `password` key in the YAML front matter: 123 | 124 | ```yaml 125 | password: 'foo' 126 | ``` 127 | 128 | Now if a user wants to visit the page, he will **have to** include `?password=foo` in the URL, otherwise he'll be presented with a 403 error. 129 | 130 | ```diff 131 | - /about 132 | + /about?password=foo 133 | ``` 134 | -------------------------------------------------------------------------------- /assets/config.php: -------------------------------------------------------------------------------- 1 | ArchTech\Pages\Page::class, 5 | 6 | 'views' => [ 7 | /** 8 | * The layout used to render the pages. 9 | * 10 | * @example app-layout For resources/views/app-layout.blade.php 11 | * @example layouts.app For resources/views/layouts.app.blade.php 12 | */ 13 | 'layout' => 'app-layout', 14 | 15 | /** 16 | * The path to your views. 17 | * 18 | * @example 'pages.' The package will look into resources/views/pages 19 | * @example 'foo::' The package will look into the 'foo' view namespace 20 | */ 21 | 'path' => 'pages.', 22 | 23 | /** 24 | * The name of the view used to render markdown pages. 25 | * 26 | * @example 'pages._markdown' The package will use resources/views/pages/_markdown.blade.php 27 | */ 28 | 'markdown' => 'pages::_markdown', 29 | ], 30 | 31 | 'routes' => [ 32 | 'name' => 'page', 33 | 'prefix' => '', 34 | 'handler' => ArchTech\Pages\PageController::class, 35 | ], 36 | ]; 37 | -------------------------------------------------------------------------------- /assets/views/_markdown.blade.php: -------------------------------------------------------------------------------- 1 | 2 |
3 |
4 |

{{ $page->title }}

5 | 6 | {!! Str::markdown($page->content) !!} 7 |
8 |
9 | 10 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "archtechx/laravel-pages", 3 | "description": "Easily add routes to your Laravel app by creating Markdown or Blade files.", 4 | "keywords": ["laravel"], 5 | "type": "library", 6 | "license": "MIT", 7 | "authors": [ 8 | { 9 | "name": "Samuel Štancl", 10 | "email": "samuel@archte.ch" 11 | } 12 | ], 13 | "autoload": { 14 | "psr-4": { 15 | "ArchTech\\Pages\\": "src/" 16 | } 17 | }, 18 | "autoload-dev": { 19 | "psr-4": { 20 | "ArchTech\\Pages\\Tests\\": "tests/" 21 | } 22 | }, 23 | "require": { 24 | "php": "^8.2", 25 | "illuminate/support": "^10.0|^11.0", 26 | "archtechx/laravel-seo": "^0.10", 27 | "ryangjchandler/orbit": "^1.3", 28 | "illuminate/routing": "^10.0|^11.0", 29 | "illuminate/database": "^10.0|^11.0" 30 | }, 31 | "require-dev": { 32 | "orchestra/testbench": "^8.0|^9.0", 33 | "pestphp/pest": "^2.0", 34 | "pestphp/pest-plugin-laravel": "^2.0" 35 | }, 36 | "extra": { 37 | "laravel": { 38 | "providers": [ 39 | "ArchTech\\Pages\\PagesServiceProvider" 40 | ] 41 | } 42 | }, 43 | "minimum-stability": "dev", 44 | "prefer-stable": true, 45 | "config": { 46 | "allow-plugins": { 47 | "pestphp/pest-plugin": true 48 | } 49 | } 50 | } 51 | -------------------------------------------------------------------------------- /src/Page.php: -------------------------------------------------------------------------------- 1 | string('slug'); 21 | $table->string('title'); 22 | $table->string('password')->nullable(); 23 | $table->longText('content'); 24 | } 25 | 26 | public function getKeyName() 27 | { 28 | return 'slug'; 29 | } 30 | 31 | public function getIncrementing() 32 | { 33 | return false; 34 | } 35 | 36 | public static function routes(): void 37 | { 38 | Route::get('/{page}', config('pages.routes.handler')) 39 | ->prefix(config('pages.routes.prefix')) 40 | ->name(config('pages.routes.name')); 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /src/PageController.php: -------------------------------------------------------------------------------- 1 | exists($view)) { 20 | return view($view); 21 | } 22 | 23 | if ($model = config('pages.model')::find($page)) { 24 | if ($model->password) { 25 | abort_unless(request()->query('password') === $model->password, 403); 26 | } 27 | 28 | seo() 29 | ->title($model->title) 30 | ->description(Str::limit($model->content, 100)); 31 | 32 | return view(config('pages.views.markdown'), ['page' => $model]); 33 | } 34 | 35 | abort(404); 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /src/PagesServiceProvider.php: -------------------------------------------------------------------------------- 1 | loadViewsFrom(__DIR__ . '/../assets/views', 'pages'); 18 | $this->mergeConfigFrom(__DIR__ . '/../assets/config.php', 'pages'); 19 | 20 | $this->publishes([ 21 | __DIR__ . '/../assets/views' => resource_path('views/vendor/pages'), 22 | ], 'archtech-pages-views'); 23 | 24 | $this->publishes([ 25 | __DIR__ . '/../assets/config.php' => config_path('pages.php'), 26 | ], 'archtech-pages-config'); 27 | } 28 | } 29 | --------------------------------------------------------------------------------