New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposed a new article about using pure PHP libraries with Assetic #5166

Merged
merged 12 commits into from Jun 27, 2015

Conversation

Projects
None yet
7 participants
@javiereguiluz
Copy link
Member

javiereguiluz commented Apr 10, 2015

Q A
Doc fix? no
New docs? yes
Applies to all
Fixed tickets -

In #5159 @wouterj proposes to create a new Cookbook section dedicated to frontend articles. I think it's a great idea and in this pull request I propose an article showing how to use pure PHP libraries to combine, compile and minimize CSS, SCSS and JS files.


{% stylesheets filter="scssphp" output="css/app.css"
"assets/scss/bootstrap.scss"
"assets/scss/font-awesome.scss"

This comment has been minimized.

@rvanlaak

rvanlaak Apr 13, 2015

Contributor

Maybe add a reference about managing FontAwesome using Bower here?

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 13, 2015

Member

I don't think that's a good idea, because this article is about using PHP only libraries. But once the Bower article written by @wouterj is published, we can indeed add a link to it in the introduction of this article (where we say "JS is the best for this"). I think taht would make a lot of sense. Thanks!

This comment has been minimized.

@rvanlaak

rvanlaak Apr 13, 2015

Contributor

👍 for adding a note. My point is that it should be clear that managing (minimize, compile) web assets with PHP is possible, but checking in "assets/scss/font-awesome.scss" in the VCS is not needed if a package manager like Bower is used.

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

👍 interesting point, yeah maybe a # this is required when done PHP exclusive compilation of assets

.. index::
single: Front-end; Assetic, Bootstrap

Combining, Compiling and Minimizing Web Assets with Pure PHP Libraries

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

should say PHP Libraries only

* If you want to simplify application deployment.

In this article you'll learn how to combine and minimize CSS and JavaScript files
and how to compile Sass SCSS files using pure PHP libraries with Assetic.

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

pure -> only or exclusively

.. code-block:: bash
$ composer require leafo/scssphp
$ composer require patchwork/jsqueeze:"~1.0"

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

make it ~1.0.7 better? or something like lesser than 2.0.0

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 13, 2015

Member

When we want to limit something to be "less than 2.0.0" I think that the ~1.0 constraint is more intuitive.

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

actually is more correct, not intuitive, because it will include 1.2 etc. Though is very unlikely. So ignore please and proceed 👍

This comment has been minimized.

@stof

stof Apr 13, 2015

Member

I was about to suggest using the 2.0 version, but actually Assetic is compatible with both 1.x and 2.x only in the dev version. I haven't released this in a stable version yet.

-------------------------------

This example shows the very common scenario of using the Bootstrap framework, the
jQuery library, the FontAwesome icon font and some regular CSS and JavaScript

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

font -> fonts?

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 13, 2015

Member

In this case we're talking about just one font, so I guess this should be kept as singular.

This comment has been minimized.

@cordoval

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 13, 2015

Member

Actually ... I think you are right. FontAwesome is just one font, but it delivers a lot of files. Strictly speaking, there are several icon fonts. I've just updated it. Thanks.

@rvanlaak

This comment has been minimized.

Copy link
Contributor

rvanlaak commented Apr 13, 2015

As mentioned in #5166 (comment) What about compiling a file that is managed by a package manager?

The example I'd like to be clear is: the scss files from FontAwesome can be managed using Bower, and can be compiled using scssphp. They even can be imported in the project's scss files right?

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Apr 13, 2015

@rvanlaak let me explain the purpose of this article: the idea is to explain how to do the usual web asset stuff WITHOUT using any JavaScript tool or technology (Bower, Gulp, Grunt, ...).

This article shows how can you achieve everything with Assetic and two PHP libraries while setting up everything in just a few minutes. So the FontAwesome files, as long as Bootstrap and jQuery files, should be committed to the repository and stored in the web/assets/ directory, as explained in the article.

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented Apr 13, 2015

i think this article should include packages such as robloach component or other bundles that bring in third party stuff. The path should be adaptable to point to those things without needing to persist the assets into the repository which is a very bad practice.

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Apr 13, 2015

@cordoval I'm afraid that adding JavaScript stuff or third-party bundles into this article can't be possible.

The intro of the article says: "using JavaScript for doing this stuff is the best way to do it" and provides a link to that solution. But if you can't or don't want to use JavaScript, then you have this article which explains the simple and pragmatic way to do it using only PHP.

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented Apr 13, 2015

I think you are not understanding what i am saying. Let me rephrase it and reiterate it to make it plain.

I mentioned @RobLoach's component only in the sense to bring css in, it has php packages that bring assets and js as well. Notice there is no js involved here. Repeating for emphasis here, they are not the js method to bring assets in. These are purely php. That said I hope is clear up to this point. I was never talking about js way of bringing assets here, which I am afraid you misunderstood.

That said, there is no need then to persist these things into the repository, or at least there is no need to persist them all. It can be done right with php as well, or the most right way with only php.

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Apr 13, 2015

@cordoval I understand you know. Thanks for explaining it in detail.

However, I still think it's not necessary. In this case, I don't consider a bad practice to persist assets in the repository. If your application is complex, use Bower and JS-stuff to continuosly update those assets. But if you application is simple enough, it's better to not update them continuously: things can break and you don't have time/money to solve those problems. So it's better to add those assets to the repo and treat them like regular assets, without updating them continuously.

Anyway, we could add a very short note about the existence of pure PHP tools to manage assets similarly to JS-stuff.

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented Apr 13, 2015

I meant to put just a note, not even a full paragraph, to avoid saying this is the only way as there are the ways i just explained.

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Apr 13, 2015

@cordoval I agree. We'll do that.

@rvanlaak

This comment has been minimized.

Copy link
Contributor

rvanlaak commented Apr 13, 2015

👍 for not using any JS tooling in the article, but following a PHP approach. Did get that, but did want to discuss the gray areas where developers could make a decision to use a slight other approach. The use of bower is only one example of that ;) I don't see any other areas atm, so adding a note/link to @wouterj 's Bower article is fine ;)

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented Apr 13, 2015

@rvanlaak i think @javiereguiluz understood what i meant. PHP approach is not just one approach is manyfold. I think this article is saying this is the best way, but if you are going to do it plainly bare bones here are the ways people approach it.

@@ -0,0 +1,7 @@
Form

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

should be Front-End

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

this will be done by my PR and can be removed from this PR, to avoid merge conflicts


The official Symfony Best Practices recommend to use Assetic to
:doc:`manage web assets </best_practices/web-assets>`, unless you are
comfortable with JavaScript-based frontend tools.

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

front-end

applications;
* If you want to simplify application deployment.

In this article you'll learn how to combine and minimize CSS and JavaScript files

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

In this article, you'll learn [...]

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

I honestly don't think this way, but I am eager to learn, what is the reasoning for this comma?

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

It's to allow this kind of crazy word order in the sentence. Without comma, you would do "You'll learn how to combine and minimize CSS and JS files in this article" (time and location are always located at the end of the sentence). This is perfectly fine when you're speaking to someone, but when reading, it's common to put the location in front of the sentence. When doing that, you must add a comma before you start the sentence: "In this article, you'll learn [...]"

(funny, in this comment I used the "prepended construction" (don't know if that's the official naming) 3 times)

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

can you please show me which of these cases is http://grammar.ccc.commnet.edu/grammar/commas.htm ? I am trying to contest this appreciation constructively 👴

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

It's 3:

Use a comma to set off introductory elements, as in "Running toward third base, he suddenly realized how stupid he looked."

It is permissible to omit the comma after a brief introductory element if the omission does not result in confusion or hesitancy in reading. If there is ever any doubt, use the comma, as it is always correct. If you would like some additional guidelines on using a comma after introductory elements, click HERE.

So, yes. You are correct that the comma can be omitted, but it can introduce confusion. As the docs are read by many non-natives, it's good to avoid anything that could introduce confusion.

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

well you agreed which is good. So it is not "it must" but it is optional. If we make this into a rule just to be always right is ok. I personally think this interlude is so short that flows immediately to the point, no need for refrain or pause. I also doubt this introduces any confusion. But 💚 🚥 light if you always want to be right. It is just i am concerned on the damage to the language over time with enforcing something that is optional indeed. But yeah let's go in agreement to put the comma 👴 The lesson I learned here is not always try to be right. 😊 because it could make it wrong.

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 14, 2015

Member

Thanks for the discussion. I'll put the comma then :)

* If you want to simplify application deployment.

In this article you'll learn how to combine and minimize CSS and JavaScript files
and how to compile Sass SCSS files using PHP only libraries with Assetic.

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

I'm no front-end expert, but is Sass SCSS the state-of-the-art technology? What about alternatives like LESS?

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

There are some alternatives, but I believe Sass is used the most and has the biggest community behind it.

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

However, I would say "Sass files". There is no need to make this overcomplicated (and using uppercase words breaks up the read flow, reducing the reading experience a bit).

Installing the Third-Party Compression Libraries
------------------------------------------------

Assetic includes a lot of ready-to-use filters but it doesn't include their

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

[...] filters, but it [...]

------------------------------------------------

Assetic includes a lot of ready-to-use filters but it doesn't include their
associated libraries. Therefore, before enabling the filters used in this article

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

[...] in this article, you must [...]

It's very important to maintain the ``~1.0`` version constraint for the ``jsqueeze``
dependency because the most recent stable version is not compatible with Assetic.

Organizing Your Web Asset Files

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

Actually, @wouterj correct me that your (lowercased) is the correct spelling (it's a closed-class word).

│   ├── _animated.scss
│   ├── ...
│   └── _variables.scss
└── font-awesome.scss

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

What is the reasoning behind storing the raw files (*.scss and not-minified JavaScript files) under web/assets?

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

big -1 for that. It's also against the best practices btw. Imo, uncompiled files should live in app/Resources/public and only the compiled onces in web/.

This comment has been minimized.

@cordoval

cordoval Apr 13, 2015

Contributor

I don't think so, well maybe best practice document says so for newcomers. Also not following best practices does not mean wrong as it seems you are conveying with the -1. Mind that since we are opening the doors at different possibilities from where the assets come from we cannot limit them, be it bundles yes, be it other packages who knows where they are, puli, or other cases will depend on which php package is used to pull the assets no?

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

My -1 was for putting them in the public files (web/). My personal opinion is to put them in app/Resources/public.

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 14, 2015

Member

I'm a bit lost with your latest suggestion:

  • In symfony/demo#5 you asked my why I put the assets in app/Resources/ and I moved them to web/ here: symfony/demo#33
  • Here I've put the assets in web/ and you ask me to put them in app/Resources/

This comment has been minimized.

@rvanlaak

rvanlaak Apr 14, 2015

Contributor

Files that should be compiled using Assetic should be in /app/Resources/ right?


.. code-block:: html+jinja

<!DOCTYPE html>

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

It's probably a good idea to add a filename comment to the top of the template.

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 14, 2015

Member

I've updated it to display {# app/Resources/views/base.html.twig #} Is that the common practice in the Symfony docs when referring to the base/layout template?

@xabbuh

This comment has been minimized.

Copy link
Member

xabbuh commented Apr 13, 2015

This article overlaps in a way with the articles from the Assetic cookbook section. We should find a way not to document thing more than once.

Assetic includes a lot of ready-to-use filters but it doesn't include their
associated libraries. Therefore, before enabling the filters used in this article
you must install two libraries. Open a command console, browse to your project
directory and execute the following commands:

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

I think it's very important to not make this article just a step-by-step solution for one problem (Sass and minifying), but make it ready to use for other libraries as well.

This mostly means that we should try to not say "Do this", but instead explain what "this" is and how we've come up with "this". In this case, it means explaining how one can find these package names. How does one know it has to install exactly these packages?

$ composer require patchwork/jsqueeze:"~1.0"
It's very important to maintain the ``~1.0`` version constraint for the ``jsqueeze``
dependency because the most recent stable version is not compatible with Assetic.

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

This should be handled by Assetic, introducing a conflict rule in their composer.json.

This comment has been minimized.

@stof

stof Apr 13, 2015

Member

The dev version of Assetic is compatible with both 1.x and 2.x actually

Organizing Your Web Asset Files
-------------------------------

This example shows the very common scenario of using the Bootstrap framework, the

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

-1 for adding "very common". It's starting to look like Symfony is sponsered by Bootstrap :) (if that is actually what happend, I would prefer to have the logo on the site rather than using it constant in the docs).

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 14, 2015

Member

I've replaced very common by common.

This simple configuration compiles the SCSS files into regular CSS files, combines
all of them, minimizes the contents and saves the output in the ``web/css/app.css``
file, which is the one that is served to your visitors.

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

Huston, we've a big sentence again :)

What do you think about: "This simple configuration compiles, combines and minifies the SCSS files into a regular CSS file that's put in web/css/app.css."

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 14, 2015

Member

Your version is much better. Thanks!

assetic:
filters:
jsqueeze: ~
# ...

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

we should show other formats:

<!-- app/config/config.xml -->
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:assetic="http://symfony.com/schema/dic/assetic">

    <assetic:config>
        <filter name="jsqueeze" />
        <!-- ... -->
    </assetic:config>
</container>
// app/config/config.php
$container->loadFromExtension('assetic', array(
    'filters' => array(
         'jsqueeze' => null,
         // ...
    ),
));

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 14, 2015

Member

Thanks for providing these alternative formats.

{% endjavascripts %}

</body>
</html>

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

we should show the PHP syntax too

filters:
scssphp:
formatter: "Leafo\\ScssPhp\\Formatter\\Compressed"
# ...

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

we have to show XML and PHP too:

<!-- app/config/config.xml -->
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:assetic="http://symfony.com/schema/dic/assetic">

    <assetic:config>
        <filter name="scssphp" formatter="Leafo\ScssPhp\Formatter\Compressed" />
        <!-- ... -->
    </assetic:config>
</container>
// app/config/config.php
$container->loadFromExtension('assetic', array(
    'filters' => array(
         'scssphp' => array(
             'formatter' => 'Leafo\ScssPhp\Formatter\Compressed',
         ),
         // ...
    ),
));
assetic:
filters:
scssphp:
formatter: "Leafo\\ScssPhp\\Formatter\\Compressed"

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

escaping the \ isn't needed and as it reduces readability, we always try to avoid it in the docs.

This comment has been minimized.

@stof

stof Apr 13, 2015

Member

if you use the double-quoted syntax, it is.

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

actually, you need the single quoted syntax, don't you? As double quotes can cause problems when \S, \F or \C are valid sequences? (there are a couple of uppercase sequence names)

This comment has been minimized.

@stof

stof Apr 13, 2015

Member

@wouterj it is fine here as the backslash is escaped. The parser will read \\ (as \) and then F, not \F

This comment has been minimized.

@xabbuh

xabbuh Apr 13, 2015

Member

I would use single quotes so that we don't need to escape backslashes.

@wouterj

This comment has been minimized.

Copy link
Member

wouterj commented Apr 13, 2015

Imo, as this is about Assetic, we should move this one to cookbook/assetic. I've created cookbook/frontend exactly to have front-end docs that are not about Assetic (as we only had Assetic docs until now). The frontend section is a help for the frontend developers that are unsure how to combine their regular tools with the Symfony framework (and also to learn the backend devs about the exciting world of frontend tooling).

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Apr 14, 2015

@wouterj I think you are right and this article should be moved back to the Assetic cookbook section instead of adding it to the new Frontend section. I've just changed it. Thanks.

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Jun 23, 2015

This PR seems to be finished. I've addressed every comment and implemented every suggestion. Can we label it as "finished"? Thanks!

@xabbuh

This comment has been minimized.

Copy link
Member

xabbuh commented Jun 24, 2015

looks good 👍

@weaverryan weaverryan merged commit f5c4d93 into symfony:2.3 Jun 27, 2015

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

weaverryan added a commit that referenced this pull request Jun 27, 2015

feature #5166 Proposed a new article about using pure PHP libraries w…
…ith Assetic (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Proposed a new article about using pure PHP libraries with Assetic

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | all
| Fixed tickets | -

In #5159 @wouterj proposes to create a new Cookbook section dedicated to frontend articles. I think it's a great idea and in this pull request I propose an article showing how to use pure PHP libraries to combine, compile and minimize CSS, SCSS and JS files.

Commits
-------

f5c4d93 Fixed an indentation problem
4b8b3fb Moved the article back to the Assetic section
07087dd Avoid the ugly double back slashes
85e6a54 Added more configuration formats
bc6ffbe Rewords and code improvements
3ea9c86 Fixed some typos and grammar issues
1f6e16c Minor fixes
cc5b630 Reworded some wrong statements
044cd73 The file extension is not needed
14d0346 Fixed the Twig lexer name
798b5b5 Added the missin index file
86da338 Proposed a new article about using pure PHP libraries with Assetic

weaverryan added a commit that referenced this pull request Jun 27, 2015

@weaverryan

This comment has been minimized.

Copy link
Member

weaverryan commented Jun 27, 2015

Merged! Nice job making this short and concise - that's the best part (and a good reason why someone might opt for the pure PHP solutions). I made some final minor tweaks at sha: bf18f16

Thanks!

weaverryan added a commit that referenced this pull request Jun 28, 2015

Merge branch '2.8'
* 2.8: (122 commits)
  moving options below basic usage
  changing a few orders of sections - mostly to move overridden after the main options
  Rewrite note a bit
  fix capitalization
  tweak headline to be consistent with 2.6
  [Contributing] [Standards] Added entry for identical comparison
  Wrap the table creation inside the class extending Command, so users know where the  comes. They can use it as standalone when needed
  [Serializer] Array Denormalization
  [Cookbook][Assetic] complete a sentence
  Fixing "Undefined method" error on Symfony 2.7
  [#5293] Tweak to link to the article about parent bundles
  Minor tweak to remove FOSUserBundle example and replace with a link to the doc about this
  overriding 3rd party bundles
  Adjust line wrapping
  Add formatting for file and method names
  Update load_balancer_reverse_proxy.rst
  removing upgrading.rst - this has already been moved into several documents in its own section
  [#5166] Minor tweaks
  Revert "Changed dump() to var_dump()"
  Changed dump() to var_dump()
  ...

@javiereguiluz javiereguiluz deleted the javiereguiluz:assetic_php branch Jan 3, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment