Introduce EntityPublishedInterface for content entities

This is a great idea, however the issue I have found that needed to be solved in the past is actually tracking the date that the item was published, which is separate to the date the item was created. Solutions currently bring the created date forward, which is semantically incorrect. This is particularly relevant when listing content in order of publication date.

Would it be possible to discuss adding this property to the node entity as part of this feature? It would be recorded on the first transition change from unpublished to published, or be identical to the created date if published immediately. Items that are then unpublished will retain this date, however would be required to bring it forward if necessary. As a result of this, the created date should then be ideally be made immutable.

interface EntityPublishedInterface {

  /**
   * Get the date that the entity was first published.
   *
   * @return \DateTime
   * @throws EntityNeverPublishedException
   *   If the entity has never been published.
   */
  public function getPublishedDate();

}

Makes sense, in which case should probably be deferred until after this is merged in.

@phenaproxima there's probably no value in adding constants to represent TRUE and FALSE for published status at the interface level. It does make sense to have the status constants if there are multiple statuses, however since there is only 2 statuses (published and not) there is no immediate added value. I guess it does accommodate for something like a 'needs review' status, which is still unpublished.

Off the back of this, if published status for an entity is a result of a series of factors (status, created date in the past, etc), then perhaps EntityPublishedInterface::setPublished() should be removed, and the entity allowed to decide what it considers to mean published - such as a simple underlying status property. If a service requires the ability to set an entity to 'published' state, then it should be segregated into a separate interface (EntityPublishableInterface) for readability, and to be explicit in that the service intends to mutate that state.

+++ b/core/lib/Drupal/Core/Entity/EntityPublishedInterface.php
@@ -0,0 +1,38 @@
+interface EntityPublishedInterface {
+
+  /**
+   * Denotes that the entity is published.
+   */
+  const STATUS_PUBLISHED = 1;
+
+  /**
+   * Denotes that the entity is not published.
+   */
+  const STATUS_UNPUBLISHED = 0;
+
+  /**
+   * Returns the entity published status indicator.
+   *
+   * Unpublished entities are only visible to their authors and to administrators.
+   *
+   * @return bool
+   *   TRUE if the entity is published.
+   */
+  public function isPublished();

Constants here are unnecessary as they are meaningless to the interface; the reason for this is because isPublished() returns bool, and not one of STATUS_PUBLISHED|STATUS_UNPUBLISHED. Using status constants would overcomplicate this, since there's nothing wrong with TRUE or FALSE regarding whether or not something is in a published state.

The interface is an abstraction for a client, and shouldn't dictate how the object implements the method. To elaborate this a bit more: the node entity has chosen to use a status property to track whether or not it is published, at the moment this is either published (1), or unpublished (0). isPublished() returns (bool) $this->getEntityKey('status'), so the method still conforms to the interface and returns a boolean, without you needing to care what the underlying state codes mean. This allows them to be changed by the entity at any point in future (so you don't have to worry about BC breaks).

+++ b/core/lib/Drupal/Core/Entity/EntityPublishedInterface.php
@@ -0,0 +1,38 @@
+  /**
+   * Sets the published status of an entity.
+   *
+   * @param bool $published
+   *   TRUE to set this entity to published, FALSE to set it to unpublished.
+   *
+   * @return \Drupal\Core\Entity\EntityInterface
+   *   The called entity.
+   */
+  public function setPublished($published);

Just because an entity has a recognised published state, does not necessarily mean that it can, or should be toggled. An interface should not require that the state can be changed / is mutable by the API, unless that is an explicit requirement by the client; in which case it should require a different interface that allows that.

For example, the following interfaces are more explicit, and are better suited to what the client would expect to do with the entity.

interface EntityPublishableInterface extends EntityPublishedInterface {

  /**
    * Transition the publication into the published state.
    *
    * @throws EntityAlreadyPublishedException
    */
  public function publish();

}

interface EntityRetractableInterface extends EntityPublishableInterface {

  /**
    * Retract the publication status of this entity.
    *
    * @throws EntityNeverPublishedException
    */
  public function retract();

}

I'd argue that #13 was right then, with the implementation constants on the abstract class; however I'd still suggest segregating the interface better so that it's more specific towards the client, and there's room for improvement.

The interface just doesn't make sense on it's own with the constants that are integers, and methods that return or accept a boolean. The behaviour you are describing is better placed with a trait if it is to direct how common functionality is implemented?