Link Manager

LinkManager is the data-access layer for the Link model. It extends ModelManager to provide consistent filtering, ordering, multi-site scoping, tag handling, eager-loading, and cache-friendly list retrieval.

---

Class overview

namespace Wncms\Services\Managers;

use Illuminate\Database\Eloquent\Builder;

class LinkManager extends ModelManager
{
    protected string $cacheKeyPrefix = 'wncms_link';
    protected string $defaultTagType = 'link_category';
    protected bool $shouldAuth = false;
    protected string|array $cacheTags = ['links'];

    public function getModelClass(): string
    {
        return wncms()->getModelClass('link');
    }
}

---

Defaults and conventions

• Model resolution: getModelClass() honors model overrides via config/wncms.php.
• Caching: Uses cacheKeyPrefix = wncms_link and cache tag links.
• Tags: Default tag type is link_category.
• Auth scoping: $shouldAuth = false (cache keys are not user-scoped).

---

Public methods

get(array $options = []): ?Model

Delegates to ModelManager::get(). Use id, slug, name, withs, wheres, cache as needed.

getList(array $options = []): mixed

Delegates to ModelManager::getList(), backed by buildListQuery() below.

getBySlug(string $slug, ?int $websiteId = null)

Convenience method to fetch a single link by slug with optional website scoping.

$link = wncms()->link()->getBySlug('my-link', websiteId: 12);

---

Filtering and options

buildListQuery() supports the following options:

Key	Type	Purpose
ids	array	string
excluded_ids	array	string
excluded_tag_ids	array	string
tags	array	string
tag_type	string	null
keywords	array	string
wheres	array	Additional where conditions and closures
status	string	null
withs	array	Relations to eager load
order	string	Sort column. Special values: random, total_views_yesterday
sequence	string	asc or desc (default desc)
select	array	string
offset	int	Offset for batching
count	int	Limit result size (0 = no limit)
website_id	int	null

Additional behavior:

• Always eager-loads media.
• Applies distinct() to avoid duplicated rows.
• Auto-adds orderBy columns to the select clause to prevent SQL errors.

---

Tag filtering

applyTagFilter() accepts:

• Tag IDs (ints)
• Tag names (strings)
• Tag model instances

It resolves to the model configured at config('wncms.models.tag') and applies withAnyTags($names, $tagType).

To change the default tag type:

$links = wncms()->link()->getList([
    'tags' => ['promo', 'sale'],
    'tag_type' => 'link_tag',
]);

---

Keyword search

applyKeywordFilter() searches over the name column:

$links = wncms()->link()->getList([
    'keywords' => ['apple', 'store'],
]);

---

Website scoping

applyWebsiteId() scopes to a website if:

• gss('multi_website') is enabled, or
• The link model’s website_mode is single/multi, and
• The model supports applyWebsiteScope().

$links = wncms()->link()->getList([
    'website_id' => 3,
]);

---

Ordering rules

The manager overrides applyOrdering() with special cases:

• Random

  $links = wncms()->link()->getList(['order' => 'random']);

  Uses inRandomOrder().

• Yesterday’s views

  $links = wncms()->link()->getList([
      'order' => 'total_views_yesterday',
      'sequence' => 'desc',
  ]);

  Behavior:

  • Adds orderBy('links.is_pinned', 'desc') first.

  • Left joins total_views as tv_y on yesterday’s date:

    ON links.id = tv_y.link_id AND tv_y.date = YESTERDAY

  • Orders by tv_y.total, then links.id desc.

  • Ensures tv_y.total is present in select if needed.

• Default / custom column

  $links = wncms()->link()->getList([
      'order' => 'order',     // or any column on links.*
      'sequence' => 'asc',
  ]);

  Behavior:

  • Orders by links.{order} then links.id desc.
  • Auto-selects any order columns not present in select.

---

Example usages

Fetch by ID:

$link = wncms()->link()->get(['id' => 42]);

List latest active links with pagination:

$links = wncms()->link()->getList([
    'status'    => 'active',
    'page_size' => 20,
    'order'     => 'order',
    'sequence'  => 'asc',
]);

Filter by category and exclude some tags:

$links = wncms()->link()->getList([
    'tags'            => ['news', 'featured'],
    'tag_type'        => 'link_category',
    'excluded_tag_ids'=> [7, 9],
    'count'           => 8,
]);

Random featured links on current website:

$links = wncms()->link()->getList([
    'website_id' => wncms()->website()->id(),
    'wheres'     => [['is_featured', true]],
    'order'      => 'random',
    'count'      => 6,
]);

Top links by yesterday’s views, pinned first:

$links = wncms()->link()->getList([
    'order'    => 'total_views_yesterday',
    'sequence' => 'desc',
    'count'    => 10,
]);

Get by slug:

$link = wncms()->link()->getBySlug('my-affiliate-link', websiteId: null);