Skip to content

Commit

Permalink
Merge pull request #47 from Pixelrobin/updated-docs
Browse files Browse the repository at this point in the history 
Updated docs
  • Loading branch information
@natewiebe13
natewiebe13 authored Oct 12, 2021
2 parents f1a3962 + e6a7d4f commit bb4dd7a
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 120 deletions.
158 changes: 38 additions & 120 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,165 +4,83 @@ PHP Library for [Feather](https://feathericons.com/).

For more information on Feather itself, please refer to their [README](https://github.com/feathericons/feather).

This project is still pretty young, and I'm still a little new to PHP. Suggestions are welcome!
## Installation

## Installing
Install `php-feather` using [Composer](https://getcomposer.org/).

php-feather uses [Composer](https://getcomposer.org/). Run the following to install it.

```
```bash
composer require pixelrobin/php-feather
```

If you want to install composer without all the tests and nodejs stuff, use `--prefer-dist`.

```
composer require pixelrobin/php-feather --prefer-dist
```

Then, don't forget to autoload your Composer packages!

```php
require 'vendor/autoload.php';
```

## Usage

### Get an icon
### Icons

`Icons` are retrieved from an `IconManager`.

```php
<?php
require 'vendor/autoload.php';
$icons = new Feather\Icons();
$icons = new \Feather\IconManager();
?>

<!-- Display the 'anchor' icon !-->
<?php echo $icons->get('feather'); ?>
<!-- Display the 'anchor' icon -->
<?php echo $icons->getIcon('anchor'); ?>

<!-- Get creative! !-->
<button class="icon-button">Learn More <?php echo $icons->get('arrow-right'); ?></button>
<!-- Get creative! -->
<button class="icon-button">
Learn More <?= $icons->getIcon('arrow-right'); ?>
</button>
```

### Get an icon with modified properties

Simply pass an array with the attributes you want. This will be merged over the `Icons` class default attributes, except for `class`, which gets concatenated to the default classes.

```php
$icons->get('feather', array('class' => 'fooclass', 'stroke-width' => 1, 'aria-label' => 'Battery icon'));
// <svg ... class="feather feather-feather fooclass", stroke-width="1", aria-label="Battery icon" ... >...</svg>
```

You can also change the default attributes in the `Icons` class if you want some attributes consistent across multiple `get` calls. The passed attributes are merged over the current attributes in the
class by default.
`Feather\IconManager::getIcon()` returns an `Icon` object. To render the icon html itself, either cast the `Icon` as a string or call its `render()` function.

```php
$icons->setAttributes(array(
'color' => 'red',
'stroke-width' => 3
));

$icons->get('mail');
// <svg ... color="red" stroke-width="3" ... >...</svg>
$icons->getIcon('anchor'); // Returns an Icon object
$html = $icons->getIcon('anchor')->render(); // Returns the icon's html
echo $icons->getIcon('anchor'); // Outputs the icon's html, since it is cast as a string
```
### Attributes

## API
Attributes can be modified on both the `IconManager` and on `Icon` objects. Attributes can be modified directly using the `setAttribute(s)` functions or by using the helper functions.

### `Feather\Icons`

Usage:
Attribute changes on the `IconManager` will affect all `Icon` objects created by the `IconManager`. Changes on `Icon` objects will only affect the individual icons.

```php
$icons = new Feather\Icons();
```

<br>
// Use on the IconManager instance to set default attributes for all icons
$icons->setAttributes(['stroke' => '#fff', 'stroke-width' => 2]);
$icons->setAttribute('stroke', '#fff');

### `Feather\Icons->get($name, $attributes = array())`
$icons->setSize(24);
$icons->setColor('#fff');
$icons->setWeight(2);
$icons->addCssClass('foo');

Gets an icon as a string. Attributes passed will be merged over the class defaults.

```php
$icons = new Feather\Icons();

// Get an icon
echo $icons->get('anchor');
// <svg ... >...</svg>

// Get an icon with modified properties
echo $icons->get('battery', array('class' => 'fooclass', 'stroke-width' => 1, 'aria-label' => 'Battery icon'));
// <svg ... class="feather feather-battery fooclass", stroke-width="1", aria-label="Battery icon" ... >...</svg>
// Or use on a single icon to only affect that one
echo $icons->getIcon('alert-triangle')->setColor('red')->setAttribute('data-alert', 'true');
```

#### Arguments

|Argument |Type |Description |
|------------|-------|---------------------------------------------------------------------------------|
|$name |string |The name of the icon. A full list can be found [here](https://feathericons.com/).|
|$attributes?|array |Attributes to modify/add (see 'Usage' above for example) |
### Accessibility

<br>

### `Feather\Icons->setAttributes($attributes, $merge = true)`

Sets default attributes of the class. These are used as default attributes for the `get` method. By default, the `$attributes` argument is merged over the current attributes in the class. You can
disable this by setting the `$merge` argument to false, but only do it if you know what you are doing.
When getting an `Icon`, alt text can be passed as an argument or can be set on the `Icon` at a later time.

```php
$icons = new Feather\Icons();

// Set some default attributes (this will be merged with the current defaults in the class)
$icons->setAttributes(array('color' => 'red', 'stroke-width' => 3));
$icons->getIcon('anchor', [], 'Icon of an anchor');

// Now they will be included with every icon
$icons->get('delete');
// <svg ... color="red" stroke-width="1" ... >...</svg>
$icon->setAltText('Icon of an anchor');
```

#### Arguments
### Aliases

|Argument |Type |Description |
|-----------|-------|---------------------------------------------------------------------------|
|$attributes|array |Attributes to add |
|$merge? |boolean|Whether to merge with the current attributes (true) or replace them (false)|

<br>

### `Feather\Icons->getAttributes()`

Get the current attributes for the class. To set it, use the `setAttributes()` method;
Aliases can be set to make larger changes across a theme easier, such as replacing the actual icon used for a specific use case. For example, what if for the close button icon, you wanted to switch
from using the `x` icon to `x-circle`. Instead of having the icon name hardcoded, you could use an alias for the use case and update the value in one place. Aliases are set on the `IconManager`.

```php
$icons = new Feather\Icons();

$attrs = $icons->getAttributes();
```

<br>

### `Feather\DEFAULT_ATTRIBUTES`

Constant array of default attributes. They are applied to every new `Icons` class. You can use this to reset the attributes of an `Icons` class.

```php
$icons = new Feather\Icons();

// Add/modify some default attributes
$icons->setAttributes( ... );

// ... do some stuff ...

// Now say you want to reset the attributes you modified to the default...
// Set merge to false to overwrite instead of merge the arrays
$icons->setAttributes(Feather\DEFAULT_ATTRIBUTES, false);
$icons->addAlias('close-button', 'x');
```

## Contributing

Feel free to open up issues and PRs for suggesstions.

Developing requires both nodejs and composer. The icons are included as a node module and built for use in php.

Better contributing docs are coming soon!
Feel free to open up issues and PRs for suggestions.

## License

Expand Down
14 changes: 14 additions & 0 deletions UPGRADE-2.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# UPGRADE FROM 1.x to 2.0

## PHP version support

- Support for PHP < 7.4 was dropped

## Classes

- `Feather\Icons` was renamed to `Feather\IconManager`

## Icons

- `Feather\Icons::get()` was renamed to `Feather\IconManager::getIcon()`
- `Feather\Icon` objects are returned by `Feather\IconManager::getIcon()` instead of a `string`

0 comments on commit bb4dd7a

Please sign in to comment.