Deprecate entity_create() in favor of a <EntityType>::create($values) or \Drupal::entityManager()->getStorage($entity_type)->create($values)

The question is if we should actually keep entity_create() as a function, as we are removing most wrapper functions like this.

The OOP/D8 way is \Drupal::entityManager()->getStorage($entity_type)->create(). Which is a bit long...

Sounds like this needs to be in the entity system component for a decision on whether to document and keep, deprecate, or remove this function. And the patch doesn't accomplish what is in the issue summary either...

Hm... That other issue at least the title is only about Taxonomy. So ... not sure. But the issue summary here is talking about documenting that this function shouldn't be used unless the entity type is unknown or in a variable, and this patch doesn't do that. Marking it deprecated is not the same thing. So we need (a) a decision and (b) probably a new patch.

I agree that we can't just mark it deprecated without a better replacement than the current OOP way. Many, many contrib modules use entity_create(), and I'd prefer at least a helper method on the entity manager so it could be called as EntityManager::create() or some such.

I came to that issue looking around for entity_create replacement rules.
I don't know where to put that patch that introduces the EntityManager::create() static method.

I didn't include the #2 patch as it seems to be applied on the wrong method.

So.... how would this work if something like file_entity wants to swap out the entity class being used for a specific entity type?

That works just fine, the new method is identical to the existing one, and create() works too, it works both for the original class and the one that was replaced, I made sure of that and I'm actively using that in our file_entity port.

However, not convinced about adding a method like that here. First, it should definitely not be static. Second, we already have multiple issues about introducing factory methods and/or making the existing ones work. See #1867228: Make EntityTypeManager provide an entity factory and #2015535: Improve instantiation of entity classes and entity controllers. They would however have slightly different purpose and that's exactly the problem (creating an object vs. creating a new entity and applying default values). Naming is hard there..

@Berdir: Yeah, seeing get_called_class() in Entity::create() seemed very suspect for me, given that we'd be hard-coding calling Drupal\file\Entity\File::create() and not Drupal\file_entity\Entity\File::create() throughout core and other contrib modules.

What would you think about moving this method to \Drupal\Core\Entity\Entity and call it something like createFromType() ? Would it be better ?
I think having a static helper for this kind of use is far better from a DX point of view than having to remember \Drupal::entityManager()->getStorage($entity_type)->create($values);. Although, there are only 81 occurences of this case (entity_create on a variable entity type) in Core, I think that contrib would use it a lot.

+++ b/core/lib/Drupal/Core/Entity/EntityManager.php
@@ -1438,4 +1438,22 @@ protected function deleteLastInstalledFieldStorageDefinition(FieldStorageDefinit
+    return \Drupal::entityManager()

Referring to the service within itself is strange. I would just stick to using the longhand.

Every example of entity_create($entity_type... that I can see in core is in tests And almost all of them are in field/entity tests. Contrib will not write tests like that. I have 55 modules in my modules folder, and exactly one call like that.

load(), loadMultiple() are actually more likely to be used in a generic way, we'd have to add corresponding methods like that as well. But again, almost all remaining calls there are in tests, everything else already has been converted to use getStorage(), often from an injected entity manager or entity storage.

This is IMHO not worth polluting the already way too big entity manager interface.

So, what's your decision?
Do you want me to create an helper or du you want me to replace these 81 occurences by the long syntax and indicate this way to solve the deprecation?

It would be nice to get an answer to #18 so we could continue with #2490966: [Meta] Replace deprecated usage of entity_create with a direct call to the entity type class in some fashion. It would be a shame to ship D8 with entity_create() everywhere, given the importance of the entity API to D8 and the amount of work given to modernize other parts of the API.

I guess the answer is that we should use

$this->entityManager->getStorage($entity_type)->create($values);

or

\Drupal::entityManager()->getStorage($entity_type)->create($values);

according to the availability of the manager in the scope.

I don't really know how to write that in a comment. Do you think the following is going to be unerstandable?

  * @deprecated in Drupal 8.x-dev, will be removed before Drupal 9.0.0. Use
 *    the <EntityType>::create() method if the entity type is known or
 *    <EntityManager>->getStorage($entity_type)->create($values) if the entity 
 *    type is variable.

+++ b/core/lib/Drupal/Core/Entity/EntityManager.php
@@ -1438,4 +1438,22 @@ protected function deleteLastInstalledFieldStorageDefinition(FieldStorageDefinit
+  public static function create($entity_type, array $values = array()) {
+    return \Drupal::entityManager()
+      ->getStorage($entity_type)
+      ->create($values);
+  }

I don't think we should add this static method. We should just tell people to do \Drupal::entityManager()->getStorage($entity_type)->create($values); if the entity type is a variable. I agree with @Berdir in #17 and others.

Re #20 I would do something like:

 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 9.0.0. Use
 *    the <EntityType>::create() method if the entity type is known or
 *    \Drupal::entityManager()->getStorage($entity_type)->create($values) if the entity 
 *    type is variable.

It seems that we have an agreement.
Here is the patch.

I prefer not adding static methods, too. :-)

Yes, but the issue title and summary still talks about doing that.

@Berdir IS and title updated. Thank you for your review.

IS is now accurate.

Committed 6cf71a2 and pushed to 8.0.x. Thanks!

Docs only changes are not frozen in beta.