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

Added an article explaining how to use Bower in Symfony #5159

Merged
merged 1 commit into from May 23, 2015

Conversation

Projects
None yet
10 participants
@wouterj
Copy link
Member

wouterj commented Apr 8, 2015

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

The documentation was only documenting Assetic to manage assets. I feel like the community is moving away from Assetic and is starting to use tools like Bower, Gulp, Grunt, etc. This first article starts at documenting how to work with these tools within your Symfony application.

@wouterj wouterj force-pushed the wouterj:frontend branch 2 times, most recently from 2d28844 to 38a11f6 Apr 8, 2015


.. tip::

If you don't want to have NodeJS on your computer, you can also BowerPHP_

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

can also use/install


By default, Bower will install all front-end dependencies in a
``bower_packages/`` in the root of your project. In Symfony, only the ``web/``
directory has public access, so you have to configure Bower to install it in

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

in -> under

the ``web/`` directory instead.

A common practice is to put your front-end dependencies in
``web/assets/vendor/``. You can configure this directory in a ``.bowerrc`` file

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

assets seems to be used already for assetic. I have seen components folder used also. Or do you think web/assets/components is better?

This comment has been minimized.

@wouterj

wouterj Apr 8, 2015

Member

I like web/assets/vendor/ (I think I stole this a few years back from Ryan's front-end talk). Afaik, Assetic is just putting them in web/

"directory": "web/assets/vendor/"
}
It is also recommended to create a ``bower.json`` file which will hold your

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

i think it is not recommended but a mandatory need right? I wonder if you could install anything inside a folder with composer install without having to have a composer.json?

This comment has been minimized.

@wouterj

wouterj Apr 8, 2015

Member

Composer needs a composer.json.

However, Bower doesn't need a bower.json file. You can just install a front-end lib with bower install flight.

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

yeah did not know that, thanks!, i also did not know about bowerphp but will probably never think on using php for that.

An Example: Installing Bootstrap
--------------------------------

Believe it or not, but you're now ready to use Bower in your Symfony

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

not sure if this is necessary to say 👍 though

This comment has been minimized.

@wouterj

wouterj Apr 8, 2015

Member

emphasing the easiness of using tools is never bad imo :)


Believe it or not, but you're now ready to use Bower in your Symfony
application. As an example, you'll now install bootstrap in your project and
include it in your layout.

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

mention perhaps where can they source it from bower.io/search url?

~~~~~~~~~~~~~~~~~~~~~~~~~

The first step obviously is to install bootstrap. You can do this by executing
``bower install``:

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

maybe this is repetitive?

This comment has been minimized.

@wouterj

wouterj Apr 8, 2015

Member

yeah, made it a bit less repetitive

Including the Dependency in your Template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now the dependencies are installed, you can include bootstrap in your template

This comment has been minimized.

@cordoval

cordoval Apr 8, 2015

Contributor

that the

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented Apr 8, 2015

good job overall 👍 @wouterj , looking forward to Gulp and the other articles

========================

Symfony and all its packages are perfectly managed by Composer. Bower is a
dependency management tool for front-end dependencies, like Twitter Bootstrap

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 8, 2015

Member

They no longer call it Twitter Bootstrap but just Bootstrap


Symfony and all its packages are perfectly managed by Composer. Bower is a
dependency management tool for front-end dependencies, like Twitter Bootstrap
or jQuery. Since Symfony isn't purely a back-end framework, it can't deliver

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 8, 2015

Member

In this phrase there is a confusing double negation. I think it should start as Since Symfony is purely a back-end framework ...

This comment has been minimized.

@wouterj

wouterj Apr 8, 2015

Member

hehe, I started with "Since Symfony isn't a front-end framework" and changed it to back-end, but forgot to remove the negation :)

Installing Bower
----------------

Bower_ is build on top of NodeJS_. Make sure you have that installed and

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 8, 2015

Member

typo: build -> built

This comment has been minimized.

@wouterj

wouterj May 3, 2015

Member

You're correct (at least, their website uses the Node.js notation). I'll update it

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

Believe it or not, but you're now ready to use Bower in your Symfony
application. As an example, you'll now install bootstrap in your project and

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 8, 2015

Member

bootstrap probably should be spelled as Bootstrap

This will install Bootstrap and its dependencies in ``web/assets/vendor/`` (or
another directory you configured).

It'll also save the package name and a version constraint in the ``bower.json``

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 8, 2015

Member

maybe we should replace in the bower.json you created by in the bower.json file you created

This comment has been minimized.

@wouterj

@wouterj wouterj force-pushed the wouterj:frontend branch from 38a11f6 to 6cc1f3e Apr 8, 2015

@wouterj

This comment has been minimized.

Copy link
Member

wouterj commented Apr 8, 2015

Thanks @cordoval and @javiereguiluz! I've applied almost all of your comments

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented Apr 8, 2015

👍

@rvanlaak

This comment has been minimized.

Copy link
Contributor

rvanlaak commented Apr 10, 2015

👍

Another helpfull note to ease the dependency deployment process would be to add the bower install command to the composer.json file scripts section:

    "scripts": {
        "post-install-cmd": [
            "bower install"
        ],
        "post-update-cmd": [
            "bower install"
        ]
    },
an alpha state. If you're using BowerPHP, use ``bowerphp`` instead of
``bower`` in the examples.

Configuring Bower in your Project

This comment has been minimized.

@xabbuh

This comment has been minimized.

@wouterj

wouterj Apr 13, 2015

Member

I don't think so, see #5155 (comment)

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

By default, Bower will install all front-end dependencies in a
``bower_packages/`` in the root of your project. In Symfony, only the ``web/``

This comment has been minimized.

@xabbuh

xabbuh Apr 11, 2015

Member

[...] in a bower_packages directory in the [...]

This comment has been minimized.

@wouterj

wouterj May 3, 2015

Member

yes, you're correct (mixing up npm and bower)

@wouterj wouterj force-pushed the wouterj:frontend branch from 6cc1f3e to 4febc8e Apr 13, 2015

@Zeichen32

This comment has been minimized.

Copy link

Zeichen32 commented Apr 13, 2015

There is also a very nice composer plugin, which does not require bower or npm to receive assets:
https://github.com/francoispluchino/composer-asset-plugin

@wouterj

This comment has been minimized.

Copy link
Member

wouterj commented Apr 13, 2015

Thanks for your comment @Zeichen32! However, I hate using Composer for anything other than PHP packages. So if anything, I wouldn't write something that recommends that :) The main point of all these different package managers is because they have another repository backend.

@javiereguiluz

This comment has been minimized.

Copy link
Member

javiereguiluz commented Apr 13, 2015

@Zeichen32 thanks for your proposal. Don't worry about @wouterj's comment. I think he's right, because this article about Bower uses "pure JavaScript stuff". However, soon there will be another article (see #5166) which will use "pure PHP stuff". I'll gladly add a note about the project you mention that allows us to not touch JavaScript for anything!

@Zeichen32

This comment has been minimized.

Copy link

Zeichen32 commented Apr 13, 2015

@javiereguiluz You're right, i did not notice the other article. 😉

Installing Bower
----------------

Bower_ is built on top of NodeJS_. Make sure you have that installed and

This comment has been minimized.

@weaverryan

weaverryan May 3, 2015

Member

It seems like Node.js seems to be the normal way to write it?

This comment has been minimized.

@xabbuh

xabbuh May 4, 2015

Member

👍 it's even what they use on their project's site

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

By default, Bower will install all front-end dependencies in a
``bower_packages/`` directory in the root of your project. In Symfony, only the

This comment has been minimized.

@weaverryan

weaverryan May 3, 2015

Member

it's bower_components/ I believe

This comment has been minimized.

@Nyholm

Nyholm May 12, 2015

Member

I can confirm that it is bower_components/.


A common practice is to put your front-end dependencies in
``web/assets/vendor/``. You can configure this directory in a ``.bowerrc`` file
in the root of your project. It's using the JSON syntax:

This comment has been minimized.

@weaverryan

weaverryan May 3, 2015

Member

I want to keep this article as short as possible, just to show the Symfony-specific stuff for Bower and avoid duplication (but still be as clear as possible). You're already actually doing a pretty good job with this. But I think we can shorten this section, something like:

Normally, Bower downloads everything into a ``bower_components/`` directory. In
Symfony, only files in the ``web/`` directory are publicly accessible, so you need
to configure Bower to download things there instead. To do that, just create a ``.bowerrc``
file with a new destination (like ``web/assets/vendor``):
another directory you configured).

It'll also save the package name and a version constraint in the ``bower.json``
file you created. This means you don't have to commit ``web/assets/vendor/``

This comment has been minimized.

@weaverryan

weaverryan May 3, 2015

Member

actually, there is disagreement on this - they don't really have a "lock" feature yet: bower/bower#1748 - last I heard, it's recommended that you DO commit the assets. But more importantly, I think this is beyond what we should talk about.

This comment has been minimized.

@rvanlaak

rvanlaak May 4, 2015

Contributor

To me, setting a fixed version in bower.json seems a better solution than committing the assets

This comment has been minimized.

@Ninir
It is also recommended to create a ``bower.json`` file which will hold your
projects front-end dependencies (just like ``composer.json`` for Composer). You
can create an empty file or use ``bower init`` to fill in some information
about your project.

This comment has been minimized.

@weaverryan

weaverryan May 3, 2015

Member

I think we should basically move this last paragraph into the next section, and shorten things as much as possible. Something like:

To create a ``bower.json`` file, just run ``bower init``. Now you're ready to start
adding things to your project. For example, to add `Bootstrap`_ to your ``bower.json``
and download it, just run:

... code-block:: bash

    $ bower install --save bootstrap

This will install Bootstrap and its dependencies in ``web/assets/vendor/`` (or
whatever directory you configured in ``.bowerrc``).

For more details on how to use Bower, check out `Bower's Docs`_.
file you created. This means you don't have to commit ``web/assets/vendor/``
(just like you didn't commit the ``vendor/`` directory). After deploy, you just
run ``bower install`` to install all required packages. Use ``bower update``
to install the latest version (that matches the version constraint).

This comment has been minimized.

@weaverryan

weaverryan May 3, 2015

Member

I'd like to remove everything between this and line 50 above with what I have in my comment.

Obviously, that's just my suggestion - please make updates or offer other suggestions :).

@weaverryan

This comment has been minimized.

Copy link
Member

weaverryan commented May 3, 2015

@wouterj I like the initiative!

@aitboudad

This comment has been minimized.

Copy link
Contributor

aitboudad commented May 11, 2015

👍

@wouterj wouterj force-pushed the wouterj:frontend branch from 4febc8e to c84f007 May 23, 2015

@wouterj

This comment has been minimized.

Copy link
Member

wouterj commented May 23, 2015

Thanks @weaverryan for your review. I've updated the article.

~~~~~~~~~~~~~~~~~~~~~~~~~

To create a ``bower.json`` file, just run ``bower init``. Now you're ready to
start adding things to your project. For example, to add `Bootstrap`_ to your

This comment has been minimized.

@xabbuh

xabbuh May 23, 2015

Member

The referenced URL at the end of the document is missing.

This comment has been minimized.

@wouterj

wouterj May 23, 2015

Member

Fixed :)

@wouterj wouterj force-pushed the wouterj:frontend branch from c84f007 to d34b772 May 23, 2015

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented May 23, 2015

one of the things I have noticed lately is the move out of bower to npm. I don't think bower should be recommended anymore since unless you lock via sha1's this will could just be as unstable for things on production. npm however has shrinkwrap which will ensure things get locked rightly. So I would say to add a note about this to really address things the right way. The situation in the js world is as if there were two composers. One with more right to claim package management already in this case npm. Of course you need to install node for both anyways so I wonder what is the point of using bower.

@wouterj

This comment has been minimized.

Copy link
Member

wouterj commented May 23, 2015

Npm is created for Node.js development, with all kind of extra features for Node.js. Bower on the other hand is written in Node.js, but created specifically for managing front-end packages, with all kind of features that are related to this.

Npm for instance downloads the complete package, including all build files, source, etc. Bower will only install things that are really needed, like the dist files. This means that when using npm, you also need to create a build script to only move the needed dist files to the web/assets/ directory.

I'm a big -1 on recommending npm instead of bower.

@cordoval

This comment has been minimized.

Copy link
Contributor

cordoval commented May 23, 2015

I would agree with you were it not the case that npm is already installed. It is imo like recommending a wrong practice [to install more stuff than needed]. I have also seen lots of packages migrating to the right npm package managing, though not all. Also there is a PR in bower trying to do the lock which is not merged so big disadvantage. And you are bypassing the stability that a lock feature begs for which is desired to make the frontend truly stable for production. Otherwise everytime you run bower install you could be getting new stuff even on production. But your choice 👴

@weaverryan weaverryan merged commit d34b772 into symfony:2.3 May 23, 2015

1 check passed

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

weaverryan added a commit that referenced this pull request May 23, 2015

feature #5159 Added an article explaining how to use Bower in Symfony…
… (WouterJ)

This PR was merged into the 2.3 branch.

Discussion
----------

Added an article explaining how to use Bower in Symfony

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

The documentation was only documenting Assetic to manage assets. I feel like the community is moving away from Assetic and is starting to use tools like Bower, Gulp, Grunt, etc. This first article starts at documenting how to work with these tools within your Symfony application.

Commits
-------

d34b772 Created Bower article
@weaverryan

This comment has been minimized.

Copy link
Member

weaverryan commented May 23, 2015

Merged! I think this is an easy win because people can easily find this article, but it's short and avoids any major maintenance of duplication. I would like to see more articles like this that answer a question a user has, even if the answer is simply pointing them to another tool(s) to use.

About npm versus bower, Wouter explained it perfectly. Here is the SO explaining it: http://stackoverflow.com/questions/18641899/what-is-the-difference-between-bower-and-npm#answers-header

But, I did open #5294, which discusses the problem if having no lock file (currently) for Bower.

Thanks!

@wouterj wouterj deleted the wouterj:frontend branch May 23, 2015

weaverryan added a commit that referenced this pull request May 23, 2015

feature #5294 Tweaks to bower entry - specifically committing deps (w…
…eaverryan)

This PR was merged into the 2.3 branch.

Discussion
----------

Tweaks to bower entry - specifically committing deps

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | n/a

This follows after #5159. The biggest addition is a short conversation about committing Bower assets.

Thanks!

Commits
-------

7f4b55e Many tweaks thanks to the team!
d526765 Small tweaks, but mostly adding a section about committing Bower assets

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment