README

使用 composer 安装

$ composer install kagagnon/bem-php

可选配置

配置是 KAGagnon\BemPhp\Helpers\BemHelper 类的静态属性。您可以在使用 BemPhp 之前编辑它们。

<?php
/**
 * Separator between block and element
 */
KAGagnon\BemPhp\Helpers\BemHelper::$element_separator = '__';

/**
 * Separator between modifer and block/element
 */
KAGagnon\BemPhp\Helpers\BemHelper::$modifier_separator = '--';

/**
 * Should @bem create a tag element
 */
KAGagnon\BemPhp\Helpers\BemHelper::$create_tag = false;

/**
 * If create_tag is true, what's the default tag name
 */
KAGagnon\BemPhp\Helpers\BemHelper::$default_tag = 'div';

/**
 * Prefix of BEM classes.
 */
KAGagnon\BemPhp\Helpers\BemHelper::$block_prefix = '';

如何使用

建议在使用 BemHelper 类之前包含一个 use 语句。或者，您可以创建辅助函数来缩短类使用。

块

您可以使用 BemHelper::startBlock( $block_name ) 指令创建一个新的块。一旦块完成，您可以使用 BemHelper::endBlock() 来关闭块。BEM 块可以嵌套用于子模块。所以这个

<?php
BemHelper::startBlock( 'block' );
    BemHelper::startBlock( 'other-block' );
    BemHelper::endBlock();
BemHelper::endBlock();

是有效语法。

类

要生成类，您可以使用 BemHelper::bemClass( [ string|array $element [, string|array $modifiers[, integer $parent_level = 0 ]]] )。

• 不传递任何参数将生成块名称。
• 传递一个字符串作为第一个参数将生成包含元素的块名称。
• 传递一个数组作为第一个参数将生成包含修饰符的块名称。
• 传递一个字符串和一个数组将生成包含元素及其修饰符的块名称。
• 传递两个字符串将生成包含元素和根据空格拆分字符串来生成修饰符的块名称。
• 父级级别整数允许在嵌套循环中使用父级 BEM 类。

请参阅以下示例

<?php
BemHelper::startBlock( 'cup' ); // Init Block "cup"
    BemHelper::bemClass(); // Generate : cup
    BemHelper::bemClass( [ 'glass' ] ); // Generate : cup cup--glass

    BemHelper::startBlock( 'spoon' ); // Init Block "spoon"
        BemHelper::bemClass(); // Generate : spoon
        BemHelper::bemClass( [ 'metallic', 'cold' ] ); // Generate : spoon spoon--metallic spoon--cold
        BemHelper::bemClass( 'sugar' ); // Generate : spoon__sugar
        BemHelper::bemClass( 'sugar', 'half-tea-spoon' ); // Generate : spoon__sugar spoon__sugar--half-tea-spoon
        BemHelper::bemClass( 'spoon-holder', '', 1 ) // Generate : cup__spoon-holder
    BemHelper::EndBlock();

    BemHelper::bemClass( 'tea' ); // Generate : cup__tea
    BemHelper::bemClass( 'coffee' ); // Generate : cup_coffee
    BemHelper::bemClass( 'coffee' , 'with-sugar' ); // Generate : cup__coffee cup__coffee--with-sugar
    BemHelper::bemClass( 'coffee' , [ 'with-sugar', 'with-milk'] ); // Generate : cup__coffee cup__coffee--with-sugar cup__coffee--with-milk
    BemHelper::bemClass( 'coffee' , 'with-sugar with-milk no-foam' ); // Generate : cup__coffee cup__coffee--with-sugar cup__coffee--with-milk cup__coffee--no-foam
BemHelper::EndBlock();

##条件修饰符

有时，您可能想要使用条件来设置修饰符，例如是否是循环的第一个或最后一个迭代。为此，您可以通过传递一个数组来设置修饰符，其中键是类名，值是条件。这样，如果条件解析为 true，则修饰符将被添加到列表中。

BemHelper::bemClass( 'coffee', [
    'with-sugar' => $has_sugar == true
] );

您可以将条件修饰符与其他修饰符混合使用，并且它与 startBlock 方法一起工作。

BemHelper::startBlock( 'cup', 'div', [
    '_modifiers' => [
        'blue',
        'is-cold' => !$has_hot_beverage,
        'is-empty' => $finished
    ]
] );

HTML 示例

<?php BemHelper::startBlock( 'article' ) ?>
   <div class="<?php BemHelper::bemClass() ?>">
       <h1 class="<?php BemHelper::bemClass( 'title' ) ?>">Article Name</h1>

       <p class="<?php BemHelper::bemClass( 'content' ) ?>">Article text...</p>

       <?php BemHelper::startBlock( 'meta' ) ?>
           <div class="<?php BemHelper::bemClass() ?>">
               <a href="..." class="<?php BemHelper::bemClass( 'link', 'inactive' ) ?>">0 comments</a>
               <a href="..." class="<?php BemHelper::bemClass( 'link', 'clear danger' ) ?>">Delete</a>
               <a href="..." class="<?php BemHelper::bemClass( 'link' ) ?>">Edit</a>
           </div>
       <?php BemHelper::endBlock(); ?>
   </div>
<?php BemHelper::endBlock(); ?>

结果到

<div class="article">
   <h1 class="article__title">Article Name</h1>

   <p class="article__content">Article text...</p>

   <div class="meta">
       <a href="..." class="meta__link--inactive">0 comments</a>
       <a href="..." class="meta__link--clear meta__link--danger">Delete</a>
       <a href="..." class="meta__link">Edit</a>
   </div>
</div>

使用 startBlock() 创建节点

您可以将参数传递给 startBlock() 以自动生成 HTML 标签。为此，您可以将标签名称作为第二个参数传递，可选地，还可以传递属性数组。

您还可以省略标签名称并传递一个数组作为第二个参数。这将根据 default_tag 配置创建 HTML 元素。

此外，如果将 create_tag 设置为 true，则 startBlock() 将始终根据 default_tag 配置创建标签（如果只传递一个参数）。

要向标签传递修饰符，只需在数组中传递 _modifiers 即可：一个用于多修饰符的数组或一个用于单修饰符的字符串。

示例

<?php
// We assume `create_tag` is set to true

BemHelper::startBlock( 'block' ) // <div class="block">
BemHelper::endBlock()            // </div>

BemHelper::startBlock( 'block', 'article' ) // <article class="block">
BemHelper::endBlock()                       // </article>

BemHelper::startBlock( 'block', 'quote', [ 'data-inspiration', 'class' => 'js-action' ] ) // <quote class="js-action block" data-inspiration >
BemHelper::endBlock()                                                                     //</quote>

BemHelper::startBlock( 'block', [ 'id' => "anchor" ] ) // <div class="block" id="anchor">
BemHelper::endBlock()                                  // </div>

BemHelper::startBlock( 'block', [ 'id' => "anchor", '_modifiers' => 'modifier' ] ) // <div class="block block--modifier" id="anchor">
BemHelper::endBlock()                                  // </div>

BemHelper::startBlock( 'block', [ '_modifiers' => [ 'modifier1', 'modifier2' ] ] ) // <div class="block block--modifier1 block--modifier2">
BemHelper::endBlock()                                  // </div>

与 Laravel (Blade 指令) 一起使用

此插件附带 Laravel 集成。您可以将 KAGagnon\BemPhp\BemServiceProvider 类包含在您的应用程序服务提供者列表中。以下指令将被映射

@bem( ... ) => BemHelper::startBlock
@bemclass( ... ) => BemHelper::bemClass
@endbem => BemHelper::endBlock

Twig 扩展

此插件附带 Twig 集成。您可以将 KAGagnon\BemPhp\Twig\BemTwigExtension 注册为 Twig 扩展。以下指令将被映射

{% bem( ... ) %} => BemHelper::startBlock
{{ bemclass( ... ) }} => BemHelper::endBlock
{% endbem %} => BemHelper::getBemClass