[TASK] Deprecate the expansion of shorthand properties

This is the backport of #714 and the tickets leading up to that:
- #578
- #580
- #579
- #577
- #576
- #575
- #574
- #573
- #572
- #571
- #570
- #569
- #566
- #567
- #558

Author: oliverklee

CHANGELOG.md

@@ -16,6 +16,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Deprecated
 
+- Deprecate the expansion of shorthand properties (#719)
 - Deprecate `Parser::setCharset()` and `Parser::getCharset()` (#703)
 
 ### Removed

src/CSSList/Document.php

@@ -128,6 +128,8 @@ public function getSelectorsBySpecificity($sSpecificitySearch = null)
      * Expands all shorthand properties to their long value.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandShorthands()
     {
@@ -140,6 +142,8 @@ public function expandShorthands()
      * Create shorthands properties whenever possible.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createShorthands()
     {

src/RuleSet/DeclarationBlock.php

@@ -181,6 +181,8 @@ public function getSelectors()
      * Splits shorthand declarations (e.g. `margin` or `font`) into their constituent parts.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandShorthands()
     {
@@ -196,6 +198,8 @@ public function expandShorthands()
      * Creates shorthand declarations (e.g. `margin` or `font`) whenever possible.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createShorthands()
     {
@@ -215,6 +219,8 @@ public function createShorthands()
      * Multiple borders are not yet supported as of 3.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandBorderShorthand()
     {
@@ -276,6 +282,8 @@ public function expandBorderShorthand()
      * Handles `margin`, `padding`, `border-color`, `border-style` and `border-width`.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandDimensionsShorthand()
     {
@@ -336,6 +344,8 @@ public function expandDimensionsShorthand()
      * into their constituent parts.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandFontShorthand()
     {
@@ -406,6 +416,8 @@ public function expandFontShorthand()
      * @see http://www.w3.org/TR/21/colors.html#propdef-background
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandBackgroundShorthand()
     {
@@ -478,6 +490,8 @@ public function expandBackgroundShorthand()
 
     /**
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function expandListStyleShorthand()
     {
@@ -561,6 +575,8 @@ public function expandListStyleShorthand()
      * @param string $sShorthand
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createShorthandProperties(array $aProperties, $sShorthand)
     {
@@ -597,6 +613,8 @@ public function createShorthandProperties(array $aProperties, $sShorthand)
 
     /**
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createBackgroundShorthand()
     {
@@ -612,6 +630,8 @@ public function createBackgroundShorthand()
 
     /**
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createListStyleShorthand()
     {
@@ -629,6 +649,8 @@ public function createListStyleShorthand()
      * Should be run after `create_dimensions_shorthand`!
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createBorderShorthand()
     {
@@ -646,6 +668,8 @@ public function createBorderShorthand()
      * and converts them into shorthand CSS properties.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createDimensionsShorthand()
     {
@@ -720,6 +744,8 @@ public function createDimensionsShorthand()
      * At least `font-size` AND `font-family` must be present in order to create a shorthand declaration.
      *
      * @return void
+     *
+     * @deprecated This will be removed without substitution in version 9.0 in #511.
      */
     public function createFontShorthand()
     {