Remove mentions of Eloquent truncate from docs

[vadimonus]

There are some issues and long dicsussions around truncate method and PostgreSQL CASCADE behaviour.
some of them (and many more pull requests):

• Truncating tables in mysql, sqlite, sqlserver abstractions do not cascade, postgres does. This is unexpected and a leaky abstraction framework#35157
• Model::truncate() cleares all foreign key records in postgres framework#29506
• [11.x] Added useCascadeTruncate method for PostgresGrammar framework#53343

Currently documentation says This means that all foreign key related records in other tables will be deleted as well.. This wording is very soft and does not highlight the full danger. Truncate cascade will fully truncate any tables, that has foreign keys pointing current table. Not only those records, that has foreign keys. Records, having null in foreign key columns will be also deleted.

While discussing if postgresql should use CASCADE in truncates, no one speaks, that using truncate is bad practice at all.

First of all, TRUNCATE SQL command is part of Data Definition Language (DDL), and DELETE is part of Data Manipulation Language (DML). So, using TRUNCATE is ok somewhere in migrations, but not in regular code. In other words, delete is for developers, truncate is for database administrators. More at https://stackoverflow.com/a/139633
Depending on sql server truncate may not respect transactions and many checks in database integrity. Delete always respects all currently enabled data integrity mechanisms (foreign keys, constraints, etc).

So, using Truncate in regular code (meaning code, that manipulates data) is bad pattern. Mentioning Truncate in the same context as Delete in the documentation gives new developers the incorrect impression that these commands are equivalent operations. We cannot change the behavior of the framework without breaking backward compatibility. But we can remove mention of truncate from the documentation, and we will save many novice developers from stupid mistakes. Experienced developers will easily find the truncate command in the source code and can use it at their own risk.

Following the rule that all undocumented methods are used at your own risk, removing the truncate method from the documentation will remove all further questions about how exactly this method should work, reducing the number of complaints to the framework developers about the fact that the method does not work as expected. This reduce need of support recently introduced PostgresGrammar::$cascadeTruncate and change it to false in future.

Introduce this change in documentation (and idea, that regular developers and new projects should not use truncate) together with release of Laravel 12 is the most gentle way to solve this complicated situation

[shaedrich]

If the method exists, it should be documented 🤷🏻 Wouldn't it make more sense to create a PR to remove it from https://github.com/laravel/framework first? Instead, you could add a warning to the docs.

[vadimonus]

@shaedrich , if you look through linked issues, you can see, that method cannot be simply removed. It comes with framework over tenth years. Even little changing it's behaviour only for postgresql to less distructive cannot be done, as it would be breaking change.
On the other hand, laravel documentation is not the place for long lecture about why you should not use truncate as DML command.
If you decide to deprecate and remove any method, first of all you will remove it from docs, and some only some releases later, from code, leaving enough time to users to make fixes. So deleting something from code cannot be done before removing from docs in most cases.
Not every public method should be documented. Currently laravel has a lot of good undocumented methods, for example Model::setAttribute, Cache::tags, Cache::flexible and many more.
As for warning in docs, it exists. But it only mentions, that you can have problems in postgresql (not mentioning unexpected data loss), but does not say, that usage in mysql with disableForeignKeyConstraints can lead to data inconsistency. What you prefer for production, data loss, as in postgresql, or incosistency, as in mysql?
Removing this method from the documentation is the most safe solution, that we can have nowdays, saving new users from that problems with that method, but not hurting existing projects

[shaedrich]

If you decide to deprecate and remove any method, first of all you will remove it from docs, and some only some releases later, from code, leaving enough time to users to make fixes. So deleting something from code cannot be done before removing from docs in most cases.

Withholding information from the actual state of the framework is, in my opinion, similar to lecturing people but with the downside that it patronizes people.

cannot be done, as it would be breaking change.

You can, however, mark methods as @deprecated in the PHPDoc or use the #[Deprecated] attribute. Most modern IDEs will show that when using said method.

[vadimonus]

Withholding information from the actual state of the framework is, in my opinion, similar to lecturing people but with the downside that it patronizes people.

Ok, can we write something like "You should think twice before using truncate method. You probably do not need it and should use delete" ?

[shaedrich]

Withholding information from the actual state of the framework is, in my opinion, similar to lecturing people but with the downside that it patronizes people.

Ok, can we write something like "You should think twice before using truncate method. You probably do not need it and should use delete" ?

As said in #10118, as long, as we explicitly write that into the docs instead of just removing it, I'd be fine with that.

But in the end, it's not for me to finally decide that.

[taylorotwell]

This could just be sent to 11.x branch for consideration.