### Install Forum Widgets Core and Widgets (Bash)

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Installs the Forum Widgets Core framework and example widget extensions using Composer. After installation, it advises enabling the extensions in the Flarum admin panel and clearing the cache.

```bash
# Install the forum widgets core framework
composer require afrux/forum-widgets-core:"*"

# Install compatible widget extensions
composer require afrux/online-users-widget:"*"
composer require afrux/forum-stats-widget:"*"
composer require afrux/top-posters-widget:"*"

# Enable extensions in Flarum admin panel
php flarum cache:clear
```

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

### Install Forum Widgets Core (Composer)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Installs the Forum Widgets Core extension using Composer. This is the primary method for adding the package to your Flarum installation.

```sh
composer require afrux/forum-widgets-core:"*"
```

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

### Create a Custom Widget Component (JavaScript)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Example of creating a custom widget component by extending the base `Widget` class from the Forum Widgets Core. It demonstrates how to define the widget's class name, icon, title, and content.

```jsx
import Widget from 'flarum/extensions/afrux-forum-widgets-core/common/components/Widget';

export default class MyWidget extends Widget {
  className() {
    // Custom class name.
    // You can also use the class "AfruxWidgets-Widget--flat" for a flat widget (not contained in a block).
    // Please avoid strong custom styling so that it looks consistent in other themes.
    return 'MyWidget';
  }

  icon() {
    // Widget icon.
    return 'fas fa-cirlce';
  }

  title() {
    // Widget title.
    // Can return empty for a titleless widget.
    return app.translator.trans('afrux-online-users-widget.forum.widget.title');
  }

  content() {
    return (
      <div className="Afrux-OnlineUsersWidget-users">
        // ...
      </div>
    );
  }
}
```

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

### Widget Placement Options TypeScript

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Define available widget placement zones and configure widget properties. The `Placement` type includes 'start_top', 'start_bottom', 'end', 'top', and 'bottom'. The `widgetConfig` example shows how to set placement, position, uniqueness, and enabled status.

```typescript
// Widget placement type definition
type Placement = 'start_top' | 'start_bottom' | 'end' | 'top' | 'bottom';

// Widget configuration with placement
const widgetConfig = {
  key: 'statsWidget',
  component: StatsWidget,
  placement: 'end',        // Right sidebar
  position: 1,             // Order within placement zone
  isUnique: true,          // Only one instance allowed
  isDisabled: false        // Enable/disable widget
};

// Placement descriptions:
// 'start_top'    - Top of left sidebar (above navigation)
// 'start_bottom' - Bottom of left sidebar (below navigation)
// 'end'          - Right sidebar
// 'top'          - Above main content area
// 'bottom'       - Below main content area

```

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

### Integrate Widgets into Forum Pages TypeScript

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Automatically inject widget sections into Flarum's `IndexPage` component using `flarum/common/extend`. This example demonstrates adding `EndWidgetSection`, `TopWidgetSection`, `BottomWidgetSection`, `StartTopWidgetSection`, and `StartBottomWidgetSection` to the forum's view and sidebar.

```typescript
// Automatic injection in js/src/forum/index.tsx
import { extend } from 'flarum/common/extend';
import IndexPage from 'flarum/forum/components/IndexPage';

// Extension automatically adds widget sections:
extend(IndexPage.prototype, 'view', function (vnode) {
  // EndWidgetSection added to sidebar
  vnode.children[1].children[0].children.push(<EndWidgetSection />);

  // TopWidgetSection and BottomWidgetSection wrap main content
  vnode.children[1].children = [
    <TopWidgetSection />,
    ...vnode.children[1].children,
    <BottomWidgetSection />
  ];
});

extend(IndexPage.prototype, 'sidebarItems', (items) => {
  // StartTopWidgetSection at top of sidebar
  items.add('startTopWidgetSection', <StartTopWidgetSection />, 100);

  // StartBottomWidgetSection at bottom of sidebar
  items.add('startBottomWidgetSection', <StartBottomWidgetSection />, -100);
});

```

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

### Require Forum Widgets Core in Extension (composer.json)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Specifies the Forum Widgets Core extension as a dependency in your Flarum extension's composer.json file. This ensures the extension is available when your extension is installed.

```json
{
  "require": {
    "flarum/core": "^1.0.0",
    "afrux/forum-widgets-core": "^0.1.0"
  }
}
```

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

### Widget Manager Programmatic Usage (TypeScript)

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

The WidgetManager instance provides methods to access and manage registered widgets. This includes retrieving widgets by placement (optionally including hidden ones), fetching a specific widget by ID, getting all widget instances, setting widget configurations, and accessing widget state.

```typescript
// Get widgets for a specific placement
const endWidgets = app.widgets.get('end');
const startTopWidgets = app.widgets.get('start_top', true); // Include hidden widgets

// Get a specific widget by ID
const widget = app.widgets.getbyId('my-extension:myWidget');

// Get all widget instances (respects configuration)
const allWidgets = app.widgets.getWidgetInstances();

// Set widget configuration
app.widgets.setConfig({
  disabled: ['extension-id:widget-key'],
  instances: [
    {
      id: 'my-extension:myWidget',
      key: 'myWidget',
      placement: 'end',
      position: 0
    }
  ]
});

// Access widget state (persisted across rerenders)
const widgetState = app.widgets.states[widget.id];
```

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

### Safe Cache Repository Adapter PHP

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Safely interact with the cache system using `SafeCacheRepositoryAdapter`. This class provides automatic fallback for unwritable storage and logs warnings on failure. It requires an instance of `Repository` and `LoggerInterface`.

```php
<?php

use Afrux\ForumWidgets\SafeCacheRepositoryAdapter;
use Illuminate\Contracts\Cache\Repository;
use Psr\Log\LoggerInterface;

class MyWidgetDataProvider
{
    protected $cache;

    public function __construct(Repository $cache, LoggerInterface $logger)
    {
        $this->cache = new SafeCacheRepositoryAdapter($cache, $logger);
    }

    public function getWidgetData()
    {
        // Automatically handles cache write failures
        // Returns null if cache is not writable (logs warning)
        return $this->cache->remember('my-widget-data', 3600, function () {
            return $this->fetchExpensiveData();
        });
    }

    protected function fetchExpensiveData()
    {
        // Expensive operation here
        return ['data' => 'value'];
    }
}

```

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

### Initialize Widget Registration (JavaScript)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Initializes the widget registration process for both the admin and forum frontends of your Flarum extension. This ensures your custom widgets are loaded and available.

```js
import registerWidget from '../common/registerWidget';

app.initializers.add('my-extension-id', () => {
  registerWidget(app);
});
```

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

### TypeScript Configuration JSON

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Configure your TypeScript project to recognize the type definitions provided by the forum-widgets-core extension. Add the specified path mapping to your `tsconfig.json` file.

```json
{
  "compilerOptions": {
    "paths": {
      "flarum/extensions/afrux-forum-widgets-core/*": [
        "../vendor/afrux/forum-widgets-core/js/dist-typings/*"
      ]
    }
  }
}

```

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

### Composer Dependency Declaration JSON

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Declare `afrux/forum-widgets-core` as a dependency in your Flarum extension's `composer.json` file. This ensures the core widgets functionality is available for your extension.

```json
{
  "name": "vendor/my-widget-extension",
  "type": "flarum-extension",
  "require": {
    "flarum/core": "^1.0.0",
    "afrux/forum-widgets-core": "^0.1.0"
  },
  "extra": {
    "flarum-extension": {
      "title": "My Widget Extension",
      "icon": {
        "name": "fas fa-puzzle-piece"
      }
    }
  }
}

```

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

### Update Forum Widgets Core Extension (Bash)

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Updates the Forum Widgets Core extension to the latest version using Composer. It also includes commands to run database migrations and clear the Flarum cache to apply any necessary changes after the update.

```bash
# Update via Composer
composer update afrux/forum-widgets-core:"*"

# Run migrations
php flarum migrate

# Clear all caches
php flarum cache:clear
```

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

### Update Forum Widgets Core (Composer)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Updates the Forum Widgets Core extension to the latest version using Composer, followed by database migration and cache clearing.

```sh
composer update afrux/forum-widgets-core:"*"
php flarum migrate
php flarum cache:clear
```

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

### Add Widget Package Typings (tsconfig.json)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Configures TypeScript to recognize the typings provided by the Forum Widgets Core package. This is done by adding a path mapping in your project's tsconfig.json file.

```json
{
  "compilerOptions": {
    "paths": {
      "flarum/extensions/afrux-forum-widgets-core/*": ["../vendor/afrux/forum-widgets-core/js/dist-typings/*"]
    }
  }
}
```

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

### Register a New Widget (JavaScript)

Source: https://github.com/afrux/forum-widgets-core/blob/main/README.md

Registers a custom widget with the Forum Widgets Core system. This script defines the widget's key, component, and placement options, and should be called from your extension's initialization.

```js
import Widgets from 'flarum/extensions/afrux-forum-widgets-core/common/extend/Widgets';

import MyWidget from './components/MyWidget';

export default function(app) {
  (new Widgets).add({
    key: 'onlineUsers',
    component: MyWidget,
    
    // Can be a callback that returns a boolean value.
    // example: () => app.forum.attribute('myCustomExtension.mySetting')
    isDisabled: false,
    
    // Is this a one time use widget ? leave true if you don't know.
    isUnique: true,
    
    // The following values are default values that can be changed by the admin.
    placement: 'end',
    position: 1,
  }).extend(app, 'my-extension-id');
};
```

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

### Create Custom Widget Component (TypeScript)

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Custom widgets are created by extending the base Widget component. This allows defining the widget's appearance, including its CSS class, icon, title, description, and content. The `content()` method renders the main body of the widget.

```typescript
// common/components/MyWidget.tsx
import Widget from 'flarum/extensions/afrux-forum-widgets-core/common/components/Widget';

export default class MyWidget extends Widget {
  className() {
    // Return custom CSS class name
    // Use "AfruxWidgets-Widget--flat" for widgets without container styling
    return 'MyCustomWidget';
  }

  icon() {
    // FontAwesome icon name
    return 'fas fa-users';
  }

  title() {
    // Widget header title (return empty string for titleless widget)
    return app.translator.trans('my-extension.forum.widget.title');
  }

  description() {
    // Optional subtitle/description
    return app.translator.trans('my-extension.forum.widget.description');
  }

  content() {
    // Main widget content
    return (
      <div className="MyCustomWidget-content">
        <ul>
          <li>Item 1</li>
          <li>Item 2</li>
          <li>Item 3</li>
        </ul>
      </div>
    );
  }
}
```

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

### Format Numbers with Suffixes using PHP Helper

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

The `pretty_number_format` PHP helper function formats large numbers into human-readable strings using K (thousands), M (millions), and B (billions) suffixes. It allows control over decimal precision for more specific formatting.

```php
<?php

use function Afrux\ForumWidgets\Helper\pretty_number_format;

// Format numbers with abbreviations
echo pretty_number_format(500);          // "500"
echo pretty_number_format(1500);         // "1.50K"
echo pretty_number_format(2500000);      // "2.50M"
echo pretty_number_format(3500000000);   // "3.50B"

// Control decimal precision
echo pretty_number_format(1234567, 1);   // "1.2M"
echo pretty_number_format(1234567, 3);   // "1.235M"
```

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

### Cache Writability Check PHP

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Check if the cache storage directory is writable before performing cache operations using the `afrux_cache_is_writable` helper function. This allows for fallbacks to direct computation if the cache is not writable and can be used to warn administrators.

```php
<?php

use function Afrux\ForumWidgets\Helper\afrux_cache_is_writable;

// Check if cache can be written to
if (afrux_cache_is_writable()) {
    // Proceed with cache operations
    $cache->put('key', 'value', 3600);
} else {
    // Fall back to direct computation
    $data = $this->computeData();
}

// Used internally by the extension to warn admins
if (!afrux_cache_is_writable()) {
    // Display warning in admin panel
    // storage/cache directory needs write permissions
}

```

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

### Register Custom Widget with Widgets Extender (JavaScript)

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Extensions can register custom widgets using the Widgets extender class. This involves providing a unique key, a component, and configuration options like placement and uniqueness. The registration is extended to the Flarum app using a specified extension ID.

```javascript
// common/registerWidget.js
import Widgets from 'flarum/extensions/afrux-forum-widgets-core/common/extend/Widgets';
import MyCustomWidget from './components/MyCustomWidget';

export default function(app) {
  (new Widgets).add({
    key: 'myCustomWidget',
    component: MyCustomWidget,
    isDisabled: false,
    isUnique: true,
    placement: 'end',
    position: 1,
  }).extend(app, 'my-extension-id');
}

// admin/index.js and forum/index.js
import registerWidget from '../common/registerWidget';

app.initializers.add('my-extension-id', () => {
  registerWidget(app);
});
```

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

### Register Admin Widget Editor Interface (TypeScript)

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Registers the widget editor page within the Flarum admin panel using the extension data API. It also outlines the structure of the widget configuration settings, including disabled widgets and instance configurations with placement and position details.

```typescript
app.extensionData
  .for('afrux-forum-widgets-core')
  .registerPage(WidgetEditor);

// Configuration saved to settings:
// Setting key: 'afrux-forum-widgets-core.config'
// Structure:
// {
//   "disabled": ["extension-id:widget-key"],
//   "instances": [
//     {
//       "id": "extension-id:widget-key",
//       "key": "widget-key",
//       "extension": "extension-id",
//       "placement": "end",
//       "position": 0
//     }
//   ]
// }
```

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

### Sort Widgets by Position TypeScript

Source: https://context7.com/afrux/forum-widgets-core/llms.txt

Sort widgets within a placement zone based on their `position` property using the `sortWidgets` utility function. This function takes an array of widgets and returns a new array sorted by position. It is used internally for rendering widgets in the correct order.

```typescript
import sortWidgets from 'flarum/extensions/afrux-forum-widgets-core/common/utils/sortWidgets';

// Get and sort widgets for a placement
const endWidgets = app.widgets.get('end', true);
const sortedWidgets = sortWidgets(endWidgets);

// Render sorted widgets
sortedWidgets.map(widget => (
  <widget.component key={widget.id} state={widget.state} />
));

// Internally uses position comparison
// function sortWidgets(widgets) {
//   return widgets.slice(0).sort((a, b) => {
//     return a.position > b.position ? 1 : a.position < b.position ? -1 : 0;
//   });
// }

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.