FBnil patch blocks

[FBnil]

I removed the regexp (although I had a working regexp, it seems PHP7 does not like multiple non-greedy patterns. The need to anchor the query to <?xml> is very dirty -- to get one match only, instead of multipe --). (I have a Perl background and am very good with regular expressions)
So I implemented the findBlockStart() and findBlockEnd() that search upto a paragraph change <w:p>, This has been tested with LibreOffice generated docx (that features <w:p>) and real MSOffice documents (that features extra parameters, nb: <w:p w:rsidR="00AC46F7" w:rsidRDefault="00AC46F7" w:rsidP="00AC46F7">). As well as a few new testcases to cover the new functionality.

What is new?

• Blocks with variables inside now expand like Rows, with #n at the end (and you can get the old behavior back with an extra parameter)
• Block functions now use the same method as Row functions to detect start/end
• Block functions now return sensible information instead of void
• You can optionally throw exceptions if you can not find a block (enabled by an extra function parameter)
• getBlock() implemented
• setBlock() implemented for closed blocks (that end with /)
• setValue() allows for linebreaks (which are converted to shift-Enter)
• Complete coverage of unit tests (including obvious missing tests) for Block functions
• Multiple same named blocks behave as before (you can replace them one by one)
• Went through phpcs and phpunit to test everything. All tests pass* All formatting passes*

Files modified:
./src/PhpWord/TemplateProcessor.php
./tests/PhpWord/OpenTemplateProcessor.php [EDIT: IS NOT REQUIRED ANYMORE]
./tests/PhpWord/TemplateProcessorTest.php

OpenTemplateProcessor is a subclass that allows access to the private fields in TemplateProcessor. This is required for good testing of the output results.

Tested with:

• phpunit --bootstrap autoload.php phpoffice/PHPWord/tests/PhpWord/TemplateProcessorTest.php
• phpcs ./src/PhpWord/TemplateProcessor.php ./tests/PhpWord/TemplateProcessorTest.php --standard=PSR2

Todo: Tested under PHP 7.0.22 maybe try older versions too (although no PHP7-only have been used).

[FBnil]

Not sure what to do with the low scores of Scrutinizer. I can roll back the duplication of code, and use less functions-in-functions? (at a cost of more duplicate code, get it to B and C instead of D)

[FBnil]

Updates on 2017-10-02

1. Single-Element Blocks ${blockname/}

You know the problem with adding lists? You need to put a block before and after one numbered list like so:

${myblock}
* ${myelement}
${/myblock}

This then can be used with cloneBlock('myblock',2) and setValue('myelement#1', 'first substitution') etc.

Now we allow this:

* ${myelement/}

And we use: cloneBlock('myelement/',2) and setValue('myelement#1/', 'first substitution') etc.
Which is more succint and easier on the eyes in a template.

2. Update files inside the working zip file.

We also added zipAddFromString(), which works like this if you want to replace an image in the docx, while keeping the position and size of that image in the document:

	$file_dir = storage_path('document_with_image.docx');
	$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor($file_dir);
	$replace = "word/media/image2.jpeg";
	$met = file_get_contents(storage_path('big.jpg'));
	$result = $templateProcessor->zipAddFromString($replace,$met);	
	$templateProcessor->saveAs(storage_path('app/public/x.docx'));
	return response()->download(storage_path('app/public/x.docx'))->deleteFileAfterSend(true); 

So "word/media/image2.jpeg" is the name of the image inside the docx/zip file. And $met is the binary content of the new image. The resulting file was tested on Office 365 and LibreOffice and works as expected.

3. Multi line values
   Also, and even though experimental, it seems to work quite well, as it has been proposed by other people and they came up with the replacement code. It allows for:
   ->setValue("var", "my \n multiline \n string");
   Which is the equivalent to shift-Enter while writing a document (stay on the same bulletpoint/tablecell, but allow multiple lines).

[FBnil]

Received confirmation it closes #1121

[FBnil]

Well, I can not get rid of the conflict, but I guess TemplateProcessor has been rewritten and is now conflicting with the parameters the old TemplateProcessor had (and I've added quite a few new parameters).

Ok, latest additions: Segments now allow to search left or right. So take a needle, find that position, in the past, we only could search around it, that is, start tag was to the left and end tag was to the right, now we can search for both start/end tags to the right or left.
For this new functionality, I had to add more code than I wanted, and of course, it was buggy. But now I just added new testcases and they now pass. So that is one bug less.

The rest of the functional additions will be through traits or subclasses.

[troosan]

@FBnil do you think you could come up with some proper unit testing for the TemplateProcessor.
Maybe we can dedicate a release (0.15) to fixing/improving this part of the code.

[FBnil]

Will try. It seems only space related problems that Travis is giving. Give me a few days.

[FBnil]

@troosan Just to be clear I understand you: Testcases for the current TemplateProcessor in dev-master ? And with "proper", that includes reflections and maybe mocking?

[troosan]

There currently are some tests defined already (in TemplateProcessorTest) but I have a feeling a lot of cases are not covered by those tests. That's the reason why we have so many issues with it. I would like to have a reasonable assurance that when we touch this class we do not break anything else. Today I really am not.

[MyDigitalLife]

I just tested there changes in my document where i'm having problems with cloning docs, using php 7.1. Looks like this definitely solved my problems. Keep up the good work! I hope this will be merged and released soon!

[FBnil]

I installed the fixer with composer require friendsofphp/php-cs-fixer
and tested then removed --dry-run to let the fixer automatically update the code:
php-cs-fixer fix --diff --verbose --dry-run src/PhpWord/TemplateProcessor.php
Glad it is green again (Scrutinizer & Travis).

My testing script is now:

PROJECT=/var/www/html/cvprima
cd $PROJECT/vendor
cp phpoffice/PHPWord/src/PhpWord/TemplateProcessor.php phpoffice/phpword/src/PhpWord/TemplateProcessor.php;
phpunit -c $PROJECT/vendor/phpoffice/PHPWord/phpunit.xml.dist --bootstrap autoload.php phpoffice/PHPWord/tests/PhpWord/TemplateProcessorTest.php   --coverage-html $PROJECT/public/coverage
cd -

cd /home/prima/github/PHPWord
phpcs ./src/PhpWord/TemplateProcessor.php ./tests/PhpWord/TemplateProcessorTest.php --standard=PSR2  --colors -v
phpmd src/,tests/ text ./phpmd.xml.dist --exclude pclzip.lib.php
phpdoc -q -d ./src -t ./build/docs --ignore "*/src/PhpWord/Shared/*/*" --template="responsive-twig"
php-cs-fixer fix --diff --verbose --dry-run ./src/PhpWord/TemplateProcessor.php
php-cs-fixer fix --diff --verbose --dry-run ./tests/PhpWord/TemplateProcessorTest.php
cd -

Now looking into making more testcases...

[MyDigitalLife]

@FBnil @troosan Any idea when this will be merged?

[troosan]

@MyDigitalLife I'd like to have a release (0.16?) dedicated to merge the different fixes/improvements on the TemplateProcessor, I guess this will need a bit of work :-P

[MyDigitalLife]

@troosan Could you create a milestone for 0.16 and add this then? If there are any other issues that need to be looked at I can give it a go.