====== PHP RFC: Flexible Heredoc and Nowdoc Indentation ======
  * Version: 0.9
  * Date: 2017-09-15
  * Author: Thomas Punt, tpunt@php.net
  * Status: Draft
  * First Published at: https://wiki.php.net/rfc/flexible_heredoc_nowdoc_indentation

**This RFC has been superseded by [[rfc:flexible_heredoc_nowdoc_syntaxes|PHP RFC: Flexible Heredoc and Nowdoc Syntaxes]]**

===== Introduction =====
The heredoc and nowdoc syntax provide the ability to create multiline strings without the hassle of having to escape all inner quotation marks. These syntaxes, however, have been eschewed in-part because of their inflexibility with respect to indentation. They break the code layout, which makes things look ugly and harder to read. This proposal therefore seeks to enable the closing marker to be indented.

===== Proposal =====
The indentation of the closing marker will change code from:
<code php>
<?php
class foo {
    public $bar = <<<EOT
bar
EOT;
}
</code>

To:
<code php>
<?php
class foo {
    public $bar = <<<EOT
    bar
    EOT;
}
</code>

The indentation of the closing marker dictates the amount of whitespace to strip from each line within the heredoc/nowdoc. So let's demonstrate these semantics with a few examples:
<code php>
// no indentation
echo <<<END
   a
  b
 c
END;
/*
   a
  b
 c
*/

// 1 space of indentation
echo <<<END
   a
  b
 c
 END;
/*
  a
 b
c
*/

// 2 spaces of indentation
echo <<<END
   a
  b
 c
  END;
/*
 a
b
c
*/

// 3 spaces of indentation
echo <<<END
   a
  b
 c
   END;
/*
a
b
c
*/

// 4 (or more) spaces of indentation
echo <<<END
   a
  b
 c
    END;
/*
a
b
c
*/
</code>

Tabs are supported as well. If tabs and spaces are intermixed (for whatever reason...), then each space and each tab is considered as 1 indentation. So if the closing marker is indented by 1 tab, and the heredoc/nowdoc body is indented by spaces, then regardless of the closing marked *looking* further indented, only 1 bit of whitespace will still be stripped from each line:
<code php>
// 1 tab indentation
echo <<<END
   a
  b
 c
	END;
/*
  a
 b
c
*/
</code>

Moral of the story: don't mix spaces and tabs...

===== Backward Incompatible Changes =====
If the closing marker was within the body of the text, where it was the first thing (minus whitespace), terminated with a `;`, and had a newline after it, then this will now be considered the ending marker. (As you can probably tell, this is a fairly unrealistic scenario...)

===== Proposed PHP Version(s) =====
The next PHP 7.x version (or 8.0, whichever comes next)

===== RFC Impact =====
None that I know of.

===== Proposed Voting Choices =====
A simple yes or no for this feature (with a 2/3 majority required).

===== Patches and Tests =====
Initial implementation: https://github.com/php/php-src/compare/master...tpunt:heredoc-nowdoc-indentation

Language specification: will be updated if the RFC is accepted.

===== Implementation =====
After the project is implemented, this section should contain 
  - the version(s) it was merged to
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature
  - a link to the language specification section (if any)

===== References =====
Links to external references, discussions or RFCs

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.