[10.x] Add APA style title helper

[hotmeteor]

This PR provides support for APA style title casing through the Str::apa($string) or str($string)->apa() helpers.

Style as defined here: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case

[antonkomarev]

Isn't it "Title Case" and not APA? I mean APA — American Psychological Association. They are using Title Case, that's all. It's pretty common case, and it should not relate to them.

[jbrooksuk]

@hotmeteor can you please revert the unrelated styling changes made in src/Illuminate/Support/Str.php.

[hotmeteor]

@antonkomarev Laravel already has both a title and headline casing method. This particular method aligns with the APA-defined way of capitalizing specific words in specific positions as a way of titling referenced works.

I'm open to renaming the method, but it's more than just title casing.

@jbrooksuk Done

[timacdonald]

I know APA often change their styling rules. What happens when they change their title casing rules?

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

[timacdonald]

An opinionated Str::taylorCase 😎

[hotmeteor]

@timacdonald Ya I legit don’t care what it’s called, I just used those rules. The point being it’s a nicer way to style titles, especially when referring to works or headlines.

Totally open to suggestions 😃

[hotmeteor]

Awesome, thanks @taylorotwell.

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

[taylorotwell]

@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.

[shaedrich]

Isn't it "Title Case" and not APA? I mean APA — American Psychological Association. They are using Title Case, that's all. It's pretty common case, and it should not relate to them.

@antonkomarev Laravel already has both a title and headline casing method. This particular method aligns with the APA-defined way of capitalizing specific words in specific positions as a way of titling referenced works.

Even if the result is different, they both result in a title case, one way or the other. One user might prefer the one style, another the other—however, mixing these two (and naming one generic and one specific!) could be quite confusing (especially since the Str helper is already bloated).

I'm open to renaming the method, but it's more than just title casing.

Speaking of being bloated, maybe the Str helper is not the right place, because it is quite generic and should be its own helper (WritingStyle?) instead (not to quote Taylor but "maybe make it a package as its use case is quite specific" then) 🤔

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 agree with the sentiment here

…

On Tue, Jan 9 2024 at 3:34 PM, Sebastian Hädrich < ***@***.*** > wrote: > > > Isn't it "Title Case" and not APA? I mean APA — American Psychological > Association. They are using Title Case, that's all. It's pretty common > case, and it should not relate to them. > > > > > @antonkomarev ( https://github.com/antonkomarev ) Laravel already has both > a title and headline casing method. This particular method aligns with the > APA-defined way of capitalizing specific words in specific positions as a > way of titling referenced works. > > Even if the result is different, they both result in a title case, one way or the other. One user might prefer the one style, another the other—however, mixing these two (and naming one generic and one specific!) could be quite confusing (especially since the Str helper is already bloated ( #47044 (comment) ) ). > > > I'm open to renaming the method, but it's more than just title casing. > > Speaking of being bloated, maybe the Str helper is not the right place, because it is quite generic and should be its own helper ( WritingStyle ?) instead (not to quote Taylor but "maybe make it a topic as its use case is quite specific" then) 🤔 > > > 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 ( https://github.com/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 ) 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() ) — Reply to this email directly, view it on GitHub ( #49572 (comment) ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AAC4NWK2AFUI2KJCP4SKPADYNWZWXAVCNFSM6AAAAABBMIGJECVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBTHAZTINJUGU ). You are receiving this because you were mentioned. Message ID: <laravel/framework/pull/49572/c1883834545 @ github. com>

[sakcaysoftware]

It's only works for English. I wonder if we can make it according to the application language? @hotmeteor @taylorotwell

[simonhamp]

Just came to say I think this is a great addition! Thanks for putting in the work @hotmeteor

[hotmeteor]

@simonhamp ❤️

@sakcaysoftware I had the same thought.

I think I might pull this all together into one package:

• different styles
• support different languages

But I have no idea if and how the different styles apply to different languages, will need contributions.

[sakcaysoftware]

@hotmeteor It's great idea. I can help for Turkish language. I think "title style" is enough for different styles you said. It is gone a be very usefull for Blog posts coming from users because not everyone pays attention to that. Basicaly, every words must be start with camelcase except conjunctions. So we should only put language spesific conjunctions array.

[sakcaysoftware]

@hotmeteor By conjunctions I mean you defined it as $minorWords in your code

[hotmeteor]

@sakcaysoftware

Here's a start of a package... I haven't even run the code 😅 But it should be enough to get it going:

https://github.com/hotmeteor/titles

[hotmeteor]

@shaedrich You may be interested in shaping this as well

[sakcaysoftware]

@hotmeteor you're verrry fast 🚀

[shaedrich]

It's only works for English. I wonder if we can make it according to the application language? @hotmeteor @taylorotwell

I think I might pull this all together into one package:

• different styles
• support different languages

But I have no idea if and how the different styles apply to different languages, will need contributions.

This circles back to the config/ file idea from my earlier post

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())

However, since talking about i18n/l10n, the better place might be the lang/ directory 🤔

EDIT: Turns out, that's exactly what you did - great 👍🏻

I think I might pull this all together into one package

Here's a start of a package... I haven't even run the code 😅 But it should be enough to get it going:

https://github.com/hotmeteor/titles

@shaedrich You may be interested in shaping this as well

Awesome! I'll definitely check it out later today!

[cmgmyr]

@hotmeteor I built a title formatter a while ago at https://github.com/cmgmyr/title-formatter, which is similar to APA, but besides capitalization, it also considers removing additional spaces and a few other special conditions. Feel free to grab any ideas from it!

[hotmeteor]

Legend, thanks @cmgmyr!

[shaedrich]

An opinionated Str::taylorCase 😎

Sounds custom-taylored to me

[falconsmilie]

@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.

APA helper is a fantastic addition to Laravel <3

The lower casing of acronyms is the only pain point we're experiencing while using it.

[caendesilva]

Love this! I had previously created a superset of the title helper, and this is even better!

[shaedrich]

@sakcaysoftware

Here's a start of a package... I haven't even run the code 😅 But it should be enough to get it going:

https://github.com/hotmeteor/titles

@shaedrich You may be interested in shaping this as well

Too bad, this never went beyond creation :/

[shaedrich]

Too bad, this never went beyond creation :/

I'm happy to inform you that I talked to @hotmeteor and he informed me that he doesn't think he's pursuing this any further, so I will continue the hotmeteor/titles project under my https://github.com/shaedrich/titles

Thanks, Adam, for bringing this to life! 👍🏻

I'm currently in the process of migrating everything. Contributions are very welcome, especially in the current planning stage.