Updated templatemap_generator to remove dep on zend-console #67

weierophinney · 2016-06-20T20:08:26Z

This patch builds on #65, incorporating the feedback I provided via a comment on the original ZendSkeletonApplication issue that began the change.

Essentially, I want to avoid adding zend-console as a dependency of zend-view.

What this patch does is remove the usage of Zend\Console\Getopt, and simplifies the usage to a single, narrow use case: cd module/ModuleName/config && ../../../vendor/bin/templatemap_generator.php ../view ../view/**/*.phtml > template_map.config.php. This command will create the file module/ModuleName/config/template_map.config.php, which will map templates to .phtml view scripts located in module/ModuleName/view/. Users would then define the template map entry in module.config.php as follows:

'template_map' => include __DIR__ . '/template_map.config.php',

This allows regeneration of the template map on-demand using the same command, without requiring parsing and updating the main module configuration file.

I believe this is the 80% use case, and developers can build out their own solutions for anything needing more customization.

Full usage is:

Generate template maps.

Usage:

templatemap_generator.php [-h|--help] templatepath <files...>

--help|-h                    Print this usage message.
templatepath                 Path to templates relative to current working
                             path; used to identify what to strip from
                             template names. Must be a directory.
<files...>                   List of files to include in the template
                             map, relative to the current working path.

The script assumes that paths included in the template map are relative
to the current working directory.

The script will output a PHP script that will return the template map
on successful completion. You may save this to a file using standard
piping operators; use ">" to write to/ovewrite a file, ">>" to append
to a file (which may have unexpected and/or intended results; you will
need to edit the file after generation to ensure it contains valid
PHP).

If only the templatepath argument is provided, the script will look for
all .phtml files under that directory, creating a map for you.

If you want to specify a specific list of files -- for instance, if you
are using an extension other than .phtml -- we recommend one of the
following constructs:

For any shell, you can pipe the results of `find`:

    $(find ../view -name '*.phtml')

For zsh, or bash where you have enabled globstar (`shopt  -s globstar` in
either your bash profile or from within your terminal):

    ../view/**/*.phtml

We recommend you then include the generated file within your module
configuration:

  'template_map' => include __DIR__ . '/template_map.config.php',

Examples:

  # Using only a templatepath argument, which will match any .phtml
  # files found under the provided path:
  $ cd module/Application/config/
  $ ../../../vendor/bin/templatemap_generator.php ../view > template_map.config.php

  # Create a template_map.config.php file in the Application module's
  # config directory, relative to the view directory, and only containing
  # .html.php files; overwrite any existing files:
  $ cd module/Application/config/
  $ ../../../vendor/bin/templatemap_generator.php ../view ../view/**/*.html.php > template_map.config.php

  # OR using find:
  $ ../../../vendor/bin/templatemap_generator.php \
  > ../view \
  > $(find ../view -name '*.html.php') > template_map.config.phpp

…ap-generator Added template map generator as bin script

Usage: templatemap_generator.php [-h|--help] templatepath files... --help|-h Print this usage message. templatepath Path to templates relative to current working path; used to identify what to strip from template names. files... List of files to include in the template map, relative to the current working path. The script assumes that paths included in the template map are relative to the current working directory. The script will output a PHP script that will return the template map on successful completion. You may save this to a file using standard piping operators; use ">" to write to/ovewrite a file, ">>" to append to a file (which may have unexpected and/or intended results; you will need to edit the file after generation to ensure it contains valid PHP). We recommend you then include the generated file within your module configuration: 'template_map' => include __DIR__ . '/template_map.config.php', Examples: # Create a template_map.config.php file in the Application module's # config directory, relative to the view directory, and only containing # .phtml files; overwrite any existing files: $ cd module/Application/config/ $ ../../../vendor/bin/templatemap_generator.php ../view/**/*.phtml > template_map.config.php

weierophinney · 2016-06-20T20:09:37Z

@RalfEggert pinging for your review, as you started this whole thing. 😄

Does the use case as demonstrated above capture what you would most likely need?

michalbundyra · 2016-06-20T20:27:38Z

Sorry, guys, do we definitely need it? What is the advantage of this script over the @Ocramius library
https://github.com/Ocramius/OcraCachedViewResolver

Let me quote @Ocramius:

This, in my opinion, is micro-optimization and complication.
zendframework/ZendSkeletonApplication#340 (comment)

@Ocramius Could you just update your library to support also PHP 5.6? Is there any problem with it?

weierophinney · 2016-06-20T20:36:00Z

@webimpress As you've already noted, OcraCachedViewResolver currently requires PHP 7 (though you can install the v3 versions if you need 5.5 or 5.6 support); additionally, it requires usage of zend-cache, which adds a number of extra dependencies beyond what we require by default in zend-mvc, and which then requires setting up a cache storage backend. The approach of templatemap_generator.php is deliberately simple and inflexible, to cover the general use case of wanting a static map that is stored as part of your application/module repository. The two approaches are not mutually exclusive.

michalbundyra · 2016-06-20T21:49:05Z

@weierophinney thanks for explanations. It makes sense.

It would be nice to have both approaches described in documentation so developers could decide what they want use. Obviously OcraCachedViewResolver has bigger functionality, but as you said also bigger requirements.
Anyway, I hope @Ocramius could add support for PHP 5.6 in v4 (because v3 does not support ZF3 modules). For now then his library can't be used with ZF3 on PHP5.6... :(

michalbundyra · 2016-06-20T21:57:35Z

bin/templatemap_generator.php

+        ? $matches['template']
+        : $template;
+
+    $template = str_replace('\\', '/', $template);


Isn't that line redundant (because of line 86)?

Yep, thanks for the catch!

- Update example for help message to reflect actual arguments - Remove redundant line

- Needs a leading slash within the quotes

Distinct: - if first argument is not a path - if no files provided

weierophinney · 2016-06-21T19:01:49Z

I've incorporated your feedback; thanks, @webimpress !

michalbundyra · 2016-06-21T19:14:23Z

@weierophinney thanks for fixes, but still I have the same results:

$ ../../../vendor/bin/templatemap_generator.php ../view ../view/**/*.phtml
<?php
return [
    'error/404' => __DIR__ . '/../view/error/404.phtml',
    'error/index' => __DIR__ . '/../view/error/index.phtml',
    'layout/layout' => __DIR__ . '/../view/layout/layout.phtml',
];

Maybe it will help:

$ echo ../view/**/*.phtml
../view/error/404.phtml ../view/error/index.phtml ../view/layout/layout.phtml

$ echo ../view/**/**/*.phtml
../view/application/index/index.phtml

Do you think it could be system dependent? I'm using OS X but the same results I've got on Windows.

michalbundyra · 2016-06-21T19:26:20Z

@weierophinney please update also docs above in PR description, these still is wrong:
$ ../../../vendor/bin/templatemap_generator.php ../view/**/*.phtml > template_map.config.php

Do we definitely need the 2nd and 3rd parameter? Maybe will be enough if we pass only path to the view directory and generate templates map of all files in this directory (and subdirectories)? Now it looks a bit redundant. I know it gives us bigger capacities of use, but I wonder how important it is. Previous script has much more parameters, and you've already removed some.

Thoughts?

weierophinney · 2016-06-21T19:28:52Z

Do you think it could be system dependent? I'm using OS X but the same results I've got on Windows.

Yes - just got everything setup on my Windows VM to test, and can confirm. I suspect it's a difference in globbing support; I've been testing on zsh, but I know that in Windows, where I run Cygwin, I've got bash, which is also the default shell on Mac. If so, it's just a matter of documentation.

weierophinney · 2016-06-21T19:29:27Z

please update also docs above in PR description

Done.

michalbundyra · 2016-06-21T19:31:59Z

If so, it's just a matter of documentation.

Yeah, but if we would like generate templates map for whole directory (with all subdirectories) it will be complicated, so maybe better as I've suggested above to pass only path to the view directory. What do you think?

weierophinney · 2016-06-21T19:40:14Z

Do we definitely need the 2nd and 3rd parameter? Maybe will be enough if we pass only path to the view directory and generate templates map of all files in this directory (and subdirectories)? Now it looks a bit redundant. I know it gives us bigger capacities of use, but I wonder how important it is. Previous script has much more parameters, and you've already removed some.

What I tried to do for this iteration of the script is follow the Unix philosophy, along with poka-yoke principles. The idea is to keep usage to a specific pattern; if you go outside that, you need to use another tool or manually create the map.

Part of this was due to wanting to remove dependencies; I see no reason why zend-view should require zend-console, particularly if it's only for this script. The other part is because the previous version had a ton of execution paths, and I'm positive not all of them were tested. Reducing the use cases helps keep it focused and ensure it works correctly.

If so, it's just a matter of documentation.
Yeah, but if we would like generate templates map for whole directory (with all subdirectories) it will be complicated, so maybe better as I've suggested above to pass only path to the view directory. What do you think?

I discovered two ways to make this work in bash.

First, and most portable across all shells, replace ../view/**/*.phtml with $(find ../view -name '*.phtml'). This is a bit unwieldy.

Second, Bash 4 introduced a globstar shell option that, for some reason, is not enabled by default. You can enable it with:

shopt -s globstar

This can be done in either your bash profile, or on the command line. Once enabled, the **/*.phtml version works correctly.

I'll update the help doc to indicate these various forms.

michalbundyra · 2016-06-21T19:58:01Z

@weierophinney one more suggestion: maybe the 3rd parameter shouldn't be mandatory, so it will be possible generate templates map for all files in provided view directory? Wouldn't it be nicer for normal use?
Your both ways are good, works, just tested, but probably not obvious and hard to remember. I know, they are described in documentation and script help, but wouldn't be nicer just call:
$ ../../../vendor/bin/templatemap_generator.php ../view ? 😄

weierophinney · 2016-06-21T20:06:00Z

one more suggestion: maybe the 3rd parameter shouldn't be mandatory, so it will be possible generate templates map for all files in provided view directory?

This would require adding a flag to indicate what view script extension to use. Using globbing means we don't need to add that flag, or assume .phtml for that use case.

Let me think about it for a bit; I definitely see your point, and we could assume that if no files are given, .phtml is assumed for the suffix; users would specify files if they want only those with a specific suffix.

…iles Simplifies usage for the default use case. If developers want to specify an alternate extension, they can use file globbing.

weierophinney · 2016-06-21T20:49:02Z

@webimpress — just pushed a commit that allows the following:

$ templatemap_generator.php ../view > template_map.config.php

This uses a leaves-only recursive directory search to find all .phtml files in that given path. If users want to specify an alternate extension, they can use file globbing or find. I'll update the help message in the issue description, and then I think this is ready. Thanks for the great feedback!

Close #67 Close #65

RalfEggert · 2016-06-23T10:08:58Z

@weierophinney

Sorry for the delay. I only find time now to look at this. Looks really great. I just notices one little issue so far. I used the template map generator for a Zend Skeleton Application project like mentioned in the docs:

  $ cd module/Application/config/
  $ ../../../vendor/bin/templatemap_generator.php ../view ../view/**/*.phtml > template_map.config.php

That created this file:

<?php
return [
    'error/404' => __DIR__ . '/../view/error/404.phtml',
    'error/index' => __DIR__ . '/../view/error/index.phtml',
    'layout/layout' => __DIR__ . '/../view/layout/layout.phtml',
];

When I use this

  $ cd module/Application/config/
  $ ../../../vendor/bin/templatemap_generator.php ../view > template_map.config.php

I get that file:

<?php
return [
    'application/index/index' => __DIR__ . '/../view/application/index/index.phtml',
    'error/index' => __DIR__ . '/../view/error/index.phtml',
    'error/404' => __DIR__ . '/../view/error/404.phtml',
    'layout/layout' => __DIR__ . '/../view/layout/layout.phtml',
];

I guess this is because of the extra directory level for the application/index/index file?

michalbundyra · 2016-06-23T10:11:20Z

@RalfEggert please read PR description or help of the script - @weierophinney described two approaches to resolve that issue

RalfEggert · 2016-06-23T10:14:21Z

@webimpress Well, to be honest, I only looked in the examples of the inline docs of that file. And that caused the missunderstanding. Maybe needs to be updated?

michalbundyra · 2016-06-23T10:19:30Z

@RalfEggert yeah, I had the same feelings, so I've asked @weierophinney to change files list to be not mandatory parameter... Please have a look on @weierophinney comment: #67 (comment)

RalfEggert · 2016-06-23T11:40:28Z

👍

Ralf Eggert and others added 4 commits June 15, 2016 21:26

Added template map generator as bin script

a6e90b9

Added some fixes

6c154b0

Merge pull request zendframework#65 from RalfEggert/feature/templatem…

e104367

…ap-generator Added template map generator as bin script

weierophinney changed the title ~~Updated templatemap_generator to remove dep on zend-conosle~~ Updated templatemap_generator to remove dep on zend-console Jun 20, 2016

weierophinney added the enhancement label Jun 20, 2016

weierophinney added this to the 2.8.0 milestone Jun 20, 2016

michalbundyra reviewed Jun 20, 2016
View reviewed changes

weierophinney added 4 commits June 21, 2016 13:49

Incorporate feedback

68ca318

- Update example for help message to reflect actual arguments - Remove redundant line

Ensure the generated path is correct

fa59ddc

- Needs a leading slash within the quotes

Write to STDERR for error cases

43a4b90

Added error messages for error situations

3fae67e

Distinct: - if first argument is not a path - if no files provided

weierophinney added 2 commits June 21, 2016 14:02

Removed autoloading; script has no dependencies!

921d601

Ensure PHP_EOL is emitted for all help messages

fc1a7f2

Document multiple methods of globbing files

fa46aff

Allow passing only the template path, as long as it contains .phtml f…

e4545a3

…iles Simplifies usage for the default use case. If developers want to specify an alternate extension, they can use file globbing.

Re-order paragraphs so the flow makes more sense.

46faa6f

weierophinney merged commit 46faa6f into zendframework:develop Jun 21, 2016

weierophinney added a commit that referenced this pull request Jun 21, 2016

Added CHANGELOG for #67

875dd3a

weierophinney added a commit that referenced this pull request Jun 21, 2016

Merge branch 'feature/65' into develop

7e3a56d

Close #67 Close #65

weierophinney deleted the feature/65 branch June 21, 2016 20:55

This was referenced Jun 23, 2016

Added Template Map Generator zendframework/ZendSkeletonApplication#340

Closed

Missing Template Map Generator zendframework/ZendSkeletonApplication#334

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated templatemap_generator to remove dep on zend-console #67

Updated templatemap_generator to remove dep on zend-console #67

weierophinney commented Jun 20, 2016 •

edited

Loading

weierophinney commented Jun 20, 2016

michalbundyra commented Jun 20, 2016

weierophinney commented Jun 20, 2016

michalbundyra commented Jun 20, 2016

michalbundyra Jun 20, 2016

weierophinney Jun 21, 2016

weierophinney commented Jun 21, 2016

michalbundyra commented Jun 21, 2016 •

edited

Loading

michalbundyra commented Jun 21, 2016

weierophinney commented Jun 21, 2016

weierophinney commented Jun 21, 2016

michalbundyra commented Jun 21, 2016

weierophinney commented Jun 21, 2016

michalbundyra commented Jun 21, 2016

weierophinney commented Jun 21, 2016

weierophinney commented Jun 21, 2016

RalfEggert commented Jun 23, 2016

michalbundyra commented Jun 23, 2016

RalfEggert commented Jun 23, 2016

michalbundyra commented Jun 23, 2016

RalfEggert commented Jun 23, 2016

Updated templatemap_generator to remove dep on zend-console #67

Updated templatemap_generator to remove dep on zend-console #67

Conversation

weierophinney commented Jun 20, 2016 • edited Loading

weierophinney commented Jun 20, 2016

michalbundyra commented Jun 20, 2016

weierophinney commented Jun 20, 2016

michalbundyra commented Jun 20, 2016

michalbundyra Jun 20, 2016

Choose a reason for hiding this comment

weierophinney Jun 21, 2016

Choose a reason for hiding this comment

weierophinney commented Jun 21, 2016

michalbundyra commented Jun 21, 2016 • edited Loading

michalbundyra commented Jun 21, 2016

weierophinney commented Jun 21, 2016

weierophinney commented Jun 21, 2016

michalbundyra commented Jun 21, 2016

weierophinney commented Jun 21, 2016

michalbundyra commented Jun 21, 2016

weierophinney commented Jun 21, 2016

weierophinney commented Jun 21, 2016

RalfEggert commented Jun 23, 2016

michalbundyra commented Jun 23, 2016

RalfEggert commented Jun 23, 2016

michalbundyra commented Jun 23, 2016

RalfEggert commented Jun 23, 2016

weierophinney commented Jun 20, 2016 •

edited

Loading

michalbundyra commented Jun 21, 2016 •

edited

Loading