Add a package that provides a publications feature

[caendesilva]

About

Publication pages adds an easy way to create custom no-code page types, with support using a custom front matter schema and Blade templates. This feature is in development at the HydePHP develop monorepository, #685, and will be published as an official HydePHP extension tied to HydePHP v1.0.

Thank you to @rgasch for suggesting and implementing this feature in #667!

Tasks before merge:

General

• Add documentation for the publications feature (@rgasch do you want to handle this?)
• Ensure 100% test coverage for publications code
• Resolve code review comments (20)

Pull Requests

• Add default values to the publication type class constructor #729
• Add pagination feature to publications #814
• Show publication list pages in navigation #839 (related: Schema option?)
• Change publication tags to use Yaml instead of Json #837
• Add a publication type validation command and helpers #841
• Set default value of add another field question to yes in make:publicationType command #840

Issues

• Change input string handler termination sequence  publications#2
• Support the new custom media directory feature for publications media publications#3
• Collect extra data like validation rules when creating a new publication type field definition publications#5
• Configurable source root for publications? publications#4

Comments

• Generate list and detail pages when creating publication types (comment)
• Generated pubtype field names should be lower/kebab case (comment)
• Move logic to SourceFileParser class (comment)
• Create class for the tag collection (comment)

Ideas/Bugs/Other

• Add visual regression tests for generated pages? (skipping for now)
• Replace validation message placeholders like validation.required
• Maybe we want to validate the schema files when running the validate command?
• Store __createdAt publications field as string instead of Unix timestamp (unable to repro atm)
• Normalize command names

Updates to the make:publication command #786

• When using php hyde make:publication foo and there are no publications at all, the current message "Error: Unable to locate any publication types. Did you create any?" might not be entirely relevant.
• Fix integers are serialized as strings
• Make sure that the proper type is selected when asked (fixed in 2be5959 / Refactor publication page creation internals #793)

Narrow scope of PR

• Cherry pick changes in ConvertsArrayToFrontMatter.php to master Update ConvertsArrayToFrontMatter to support passing flags to dumper #801
• Cherry pick changes in VirtualPage.php to master Virtual page improvements #831
• Cherry pick Pagination feature to master Add a pagination component #832
• Remove custom validation rule Replace custom boolean validation rule with input normalizing #835

Design questions to confer with rgasch

• Should pagination be enabled by default? (Disabled in c4df021, 6acde59) (probably yes, as it's more future proof as eventually pagination will likely be desired)
• Composer attribution
• Tags as yml? (sure (or maybe both?))
• Navigation links to list pages? (yes)
• Confirm if list/detail is best or if we should go with show/index. Or single/list (I feel detail is a bit confusing)
• Are the default pagination templates named well? And are they satisfactory?

Documentation (draft)

Publications

Introduction

Publication pages adds an easy way to create custom no-code page types, with support using a custom front matter schema and Blade templates.

Creating your first publication type

Overview

Publication types provide the rules and structure for the publication pages within. At their core, a publication type is just a JSON schema file in a top-level directory of your HydePHP project. When adding publication pages, you put the Markdown files in that directory, along with any [#templates] you want to use for compiling them.

Getting started

It could not be simpler to get started! All you need to do is enter the php hyde make:publicationType command in your terminal, and you will be asked to fill in details in the interactive prompt.

[img]

Once done, the command will generate a new directory based on the selected name, as well as a few files:

schema.json - This file defines information for Hyde on how to render your publications, as well as the front matter types used by the pages.
list.blade.php - This file will be used when rendering the index page (or pages if you enabled pagination)
detail.blade.php - This file is used to render a single publication page

Creating publication pages

Overview

Publication pages are nothing more than Markdown files in your publication’s directory. They function very similarly to [#blog posts] and [#Markdown pages] and can even be scaffolded the same way

Features

Pagination…
Validation…

[codecov]

Codecov Report

Merging #685 (9896fc2) into master (e11f339) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##             master     #685     +/-   ##
===========================================
  Coverage     99.97%   99.97%             
- Complexity     2678     3388    +710     
===========================================
  Files           304      360     +56     
  Lines          6978     9164   +2186     
===========================================
+ Hits           6976     9162   +2186     
  Misses            2        2             

Impacted Files	Coverage Δ
packages/publications/src/Actions/CreateAction.php	100.00% <100.00%> (ø)
...ications/src/Actions/CreatesNewPublicationPage.php	100.00% <100.00%> (ø)
...ications/src/Actions/CreatesNewPublicationType.php	100.00% <100.00%> (ø)
...tions/src/Actions/GeneratesPublicationTagPages.php	100.00% <100.00%> (ø)
...ications/src/Actions/PublicationFieldValidator.php	100.00% <100.00%> (ø)
...blications/src/Actions/PublicationPageCompiler.php	100.00% <100.00%> (ø)
...lications/src/Actions/PublicationPageValidator.php	100.00% <100.00%> (ø)
...cations/src/Actions/PublicationSchemaValidator.php	100.00% <100.00%> (ø)
...publications/src/Actions/SeedsPublicationFiles.php	100.00% <100.00%> (ø)
...ations/src/Commands/Helpers/InputStreamHandler.php	100.00% <100.00%> (ø)
... and 18 more

... and 28 files with indirect coverage changes

[caendesilva]

Are list and detail the best names for templates? Maybe we should match Laravel and use show and index?

Edit: List and detail are probably best for now.

[caendesilva]

From Robert RE: Generate list and detail pages when creating publication types

That is a good idea, it could just be a simple/stupid template which does

{{ $fieldName}}: {{ $fieldValue}

Maybe something a bit more involved, but some sort of basic generic template which displays the data

[caendesilva]

Generated pubtype field names should be lower/kebab case

Done: they are converted via Str::slug()

[caendesilva]

Some notes for me to circle back on later(tm)

1. I think the default values used in the make pubtype command can be set as default values in the constructor as it is extremely verbose, making it bulky to test. 2. Consider putting the tag collection in a tag collection class to move all that logic to one place. Maybe, as it might be overengineering.

Update: All resolved

[caendesilva]

GitHub Copilot gave me an idea. What if instead of a schema.json for publications, we actually generate a PHP class? That would ensure direct type safety and reduce parsing. Something to experiment with maybe?

[caendesilva]

I also want to make the publications source root configurable, for example by having them all in a publications/ directory.

[rgasch]

So:

1. Generate a PHP Class instread of json: could be done, I'm not sure if it's a good idea, because quite frankly more people will know how to edit a json than how to edit a PHP class. It's not a bad idea, I just wonder what the 'cost' of doing it that way would be (in terms of accessability & adoption).

2. Configurable publication dir: If we assume that all content would be under the /content directory and that we wouldn't have the hardcoded blogs thing anymore, then isn't that just the same as having a configurable "content" directory?

[caendesilva]

So:

1. Generate a PHP Class instread of json: could be done, I'm not sure if it's a good idea, because quite frankly more people will know how to edit a json than how to edit a PHP class. It's not a bad idea, I just wonder what the 'cost' of doing it that way would be (in terms of accessability & adoption).
2. Configurable publication dir: If we assume that all content would be under the /content directory and that we wouldn't have the hardcoded blogs thing anymore, then isn't that just the same as having a configurable "content" directory?

1: Thanks for your thoughts, it was just a random idea I had, but you're right, JSON is probably easier.

2: Right, my sleepy brain forgot about that!

[caendesilva]

Oh sorting out some composer merge conflicts, I'm reminded, we probably should move illuminate/validation to the framework package... (*Note to later self)

[caendesilva]

RE: f87dac1 We might want to show index (list) pages in navigation. Idea for later...

Edit: Could also be something to put in the schema

[caendesilva]

The range validations add a very large amount of complexity. I'm starting to think about how much we really need them. Sure length validation for article descriptions might be good, but do we really need to validate date ranges and integer values? Maybe it would be better to allow arbitrary Laravel validation rules to be specified in the schema file instead of its min/max values.

Originally posted by @caendesilva in #765 (comment)

[caendesilva]

While the package is not done, I think I will soon merge this as the size of this PR is so massive, it will help the polishing phase to be more granular.