API/nomenclature

[shaedrich]

Another thing, we have to address, is how we approach designing the API (no, not the REST one):

Maybe the Str helper is not the right place, because it is quite generic and should be its own helper (WritingStyle?) instead.

the heading rules changed from version 6 to version 7 where previously not all titles where "Title Case", but some where "Sentence case".

Does that mean, there would need to be a versioning like with the ramsey/uuid package? For example, (new ApaStyle(version: 7))->apply($text) (implements WritingStyle interface)

Could moving towards this as the "new" titleCase be something for 11.x instead?

@hotmeteor Possibly? I think one improvement to this entire use case could also be the addition of configurable "acronyms". Rails allows this, so that you can do Str::title('your CSV'); and have it be accurately titled.

Another possibility than the one mentioned above would be to combine different styling options into their respective methods like this: Str::title($title, style: WritingStyle::APA)

As for the rules, this could even made entirely configurable by adding a new configuration file (config/writing_style.php, similar to larastan) with rules like either

return [
    'rules' => [
        \Apa\TitleCase::class,
        \\ \Apa\SentenceCase::class,
        \\ \ChicagoStyle\SerialComma::class,
    ],
];

or

return [
    'title_case' => Env::get('WRITING_STYLE_TITLE_CASE', WritingStyle::APA->value), // 'apa'
    'serial_comma' => Env::get('WRITING_STYLE_SERIAL_COMMA', false),
];

Optionally, overwrites could be passed to Str::style($text, [ 'serial_comma' => true ]) (or WritingStyle::apply())

[hotmeteor]

I definitely think it should be its own independent helper, and maybe there's a Str wrapper for it. I think you're on the right track with WritingStyle. Maybe the package is called "Writer" and you're interacting with a Style class.

So if I was to use this on it's own I'd want to be able to do stuff like:

// Style a title
$title = Style::title('This is my title');

// Style a date
$date = Style::date('2024-01-01 14:00:00');

// Style a date from a Carbon/DateTime instance
$date = Style::date($carbonInstance);

// Override the format
$chicagoTitle = Style::title('This is my title', StyleFormat::Chicago);

The defaults would be set in the service provider:

new StyleFactory(
    style: config('writer.style'),
    language: config('writer.lang')   
)

[shaedrich]

Yep, sounds good 👍🏻

I totally forgot to list service provider as a configuration option 😅

Yeah, that's why the package name might not be ideal

[shaedrich]

I think, Writer might be too ambigious :thinking: (see #6)