PHPackages                             obelaw/ium-url - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. obelaw/ium-url

ActiveLibrary[Utility & Helpers](/categories/utility)

obelaw/ium-url
==============

URL

04↑2900%PHPCI passing

Since Jun 9Pushed todayCompare

[ Source](https://github.com/obelawium/url)[ Packagist](https://packagist.org/packages/obelaw/ium-url)[ RSS](/packages/obelaw-ium-url/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Obelawium URL Management Module (`obelaw/ium-url`)
==================================================

[](#obelawium-url-management-module-obelawium-url)

A modular core package for Obelawium (IUM), a Laravel ERP framework, designed for complete URL management, link shortening, click tracking, and privacy-safe link analytics.

Core Features
-------------

[](#core-features)

- **Fluent API Integration**: Access all functionality fluently via the global helper: `ium()->url()`.
- **Strict Type Safety**: All operations leverage dedicated Data Objects for input/query mapping (e.g., `ShortenUrlData`, `TrackUrlData`, `UrlStatsData`, `UrlStatsData`).
- **Unique vs Total Visitors Analytics**: High-performance counting separating absolute clicks from unique visitor impressions (IP + User Agent distinct aggregation).
- **Privacy-Safe Tracking**: Automatically masks IPv4 and IPv6 addresses before storing them in compliance with GDPR.
- **Decoupled Device Parser**: Analyzes user agent headers to categorize clients into `desktop`, `mobile`, `tablet`, `robot`, or `other` without heavy third-party vendor dependencies.
- **Database Prefix Compliance**: Models and migrations extend Obelawium bases (`ModelBase` and `MigrationBase`) to comply with prefix-scoped table registries (`ium_url_*`).

---

Directory Structure
-------------------

[](#directory-structure)

```
src/
├── Base/
│   ├── MigrationBase.php    # Base migration adding 'ium_url_' table prefix
│   └── ModelBase.php        # Base model adding 'ium_url_' table prefix
├── Data/
│   ├── ShortenUrlData.php    # DTO validating shortening parameters
│   ├── TrackUrlData.php      # DTO encapsulating visitor request context
│   ├── UrlStatsData.php     # DTO encapsulating analytics filter criteria
│   ├── UrlStatsData.php     # DTO representing stats filter criteria
│   └── UrlStatsResultData.php # Immutable stats report payload containing unique counts
├── Models/
│   ├── Link.php             # Eloquent model representing shortened links
│   └── Click.php            # Eloquent model logging redirect click events
├── Providers/
│   └── URLServiceProvider.php # Binds the UrlService macro on the ium() helper
├── Services/
│   └── UrlService.php       # Domain Service executing core business logic
└── Utils/
    ├── IpAnonymizer.php     # Cleans visitor IP logs
    └── UserAgentParser.php  # Parses device classifications from User Agents

```

---

Usage Examples
--------------

[](#usage-examples)

### 1. Shorten a URL

[](#1-shorten-a-url)

Use the DTO constructor to validate arguments and shorten the link via the `shorten` service method:

```
use Obelaw\Ium\Url\Data\ShortenUrlData;

// Shortens URL and returns an instance of Obelaw\Ium\Url\Models\Link
$link = ium()->url()->shorten(new ShortenUrlData(
    url: 'https://github.com/obelaw/ium',
    code: 'github',              // Optional custom code (will auto-generate 6-char random alphanumeric if null)
    expiresAt: now()->addMonth(), // Optional link expiration
    status: 'active'             // Initial status: active / inactive
));

echo $link->code; // "github"
```

### 2. Redirection & Click Tracking

[](#2-redirection--click-tracking)

Pass the visitor's request details from the HTTP layer to the decoupled tracking service.

```
use Obelaw\Ium\Url\Data\TrackUrlData;

$trackDto = new TrackUrlData(
    ipAddress: request()->ip(),
    userAgent: request()->userAgent(),
    referrer: request()->headers->get('referer')
);

// Returns Link model and records click info if active and unexpired, otherwise returns null
$link = ium()->url()->track($code, $trackDto);

if ($link) {
    return redirect()->away($link->original_url);
}

abort(404);
```

### 3. Get Filtered Analytics

[](#3-get-filtered-analytics)

Retrieve access aggregates, device distributions, and click referrers. You can filter the results using date ranges and device types.

```
use Obelaw\Ium\Url\Data\UrlStatsData;

$filter = new UrlStatsData(
    startDate: now()->subDays(30),
    deviceType: 'mobile'
);

$analytics = ium()->url()->analytics($link->id, $filter);

echo "Total Clicks: " . $analytics['total_clicks'];
print_r($analytics['clicks_by_device']);   // e.g., ['mobile' => 12]
print_r($analytics['clicks_by_referrer']); // e.g., ['Direct' => 5, 'github.com' => 7]
```

### 4. Fetch Link Statistics (Total vs Unique Visitors)

[](#4-fetch-link-statistics-total-vs-unique-visitors)

Get detailed, index-friendly aggregate counts separating total link clicks from unique visitors.

```
use Obelaw\Ium\Url\Data\UrlStatsData;

$statsData = new UrlStatsData(
    linkId: $link->id,
    startDate: now()->subDays(14)
);

// Returns Obelaw\Ium\Url\Data\UrlStatsResultData
$report = ium()->url()->stats($statsData);

echo "Total Interactions: " . $report->totalClicks; // captures all clicks
echo "Unique Visitors: " . $report->uniqueClicks;    // captures unique IP + User Agent pairs
echo "Conversion Ratio: " . $report->uniqueRatio . "%";
```

---

Running Tests
-------------

[](#running-tests)

Verify everything runs correctly by launching the Pest test suite:

```
composer test
```

###  Health Score

22

↑

LowBetter than 22% of packages

Maintenance65

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/31162701?v=4)[komicho](/maintainers/komicho)[@komicho](https://github.com/komicho)

---

Top Contributors

[![komtcho](https://avatars.githubusercontent.com/u/12757671?v=4)](https://github.com/komtcho "komtcho (6 commits)")

### Embed Badge

![Health badge](/badges/obelaw-ium-url/health.svg)

```
[![Health](https://phpackages.com/badges/obelaw-ium-url/health.svg)](https://phpackages.com/packages/obelaw-ium-url)
```

###  Alternatives

[danog/primemodule

Prime module capable of doing prime factorization of huge numbers very quickly."

18789.0k8](/packages/danog-primemodule)[mad-web/nova-horizon-link

Smart Link for Laravel Nova to Horizon Dashboard.

24201.5k](/packages/mad-web-nova-horizon-link)[tonegabes/filament-better-options

Filament form components for better radio and checkbox options.

168.1k](/packages/tonegabes-filament-better-options)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)