laravel-metrics-plausible

Laravel Metrics Plausible은 Plausible Analytics Stats API v2를 감싸 분석 데이터를 조회하고 관리할 수 있는 직관적인 Laravel 네이티브 인터페이스를 제공하는 PHP 라이브러리입니다. 주요 기능 - 집계된 총계 조회 (방문자, 페이지뷰, 이탈률 등) - 사용자 지정 날짜 범위 및 차원(시간별, 일별, 월별)을 활용한 시계열 데이터 조회 - 페이지, 진입/이탈 페이지, 유입 경로, 채널, UTM 파라미터, 국가, 지역, 도시, 기기, 브라우저, 운영체제별 세부 분석 조회 - 목표 전환, 사용자 지정 이벤트 및 실시간 방문자 수 확인 - Plausible 사이트 및 목표 관리 (목록 조회, 생성, 삭제) - API 페이로드를 반영하는 쿼리 빌더를 사용해 맞춤형 쿼리 생성 - 특정 예외를 통해 인증, 요청 제한(rate-limit) 및 일반적인 API 오류 처리 - Plausible Cloud 및 자체 호스팅 Community Edition 모두 지원 - spatie/laravel-settings를 통해 데이터베이스에 설정을 저장하므로 별도의 설정 파일 불필요 설치 1. 패키지 추가: composer require jeffersongoncalves/laravel-metrics-plausible 2. 마이그레이션을 실행하여 설정 테이블 생성: php artisan migrate 설정 마이그레이션 후, 환경 변수가 설정의 시드 데이터로 사용됩니다. PLAUSIBLE_API_KEY – Plausible Settings → API Keys에서 발급받은 API 키 PLAUSIBLE_SITE_ID – 사이트 도메인 (예: example.com) PLAUSIBLE_BASE_URL – Plausible 기본 URL (기본값 https://plausible.io, 자체 호스팅 시 변경 가능) 설정은 PlausibleSettings 클래스를 통해 프로그래밍 방식으로 업데이트할 수도 있습니다. 사용법 개요 모든 상호작용은 Plausible 파사드를 통해 수행됩니다. 집계 총계: $stats = Plausible::aggregate(); $stats->visitors(); // 1234 $stats->pageviews(); // 4321 시계열: $rows = Plausible::timeseries(DateRange::Last30Days, Dimension::TimeDay); foreach ($rows as $row) { echo $row->label . ': ' . $row->visitors(); } 세부 분석(페이지, 유입 경로, 국가, 기기 등)은 Plausible::pages(), Plausible::countries(), Plausible::devices()와 같은 전용 메서드를 통해 사용할 수 있습니다. 실시간 방문자: $visitors = Plausible::realtimeVisitors(); 맞춤형 쿼리: $query = Plausible::query() ->metrics(Metric::Visitors, Metric::Pageviews) ->dateRange(DateRange::Last7Days) ->dimensions(Dimension::Page) ->filter('is', Dimension::Country, ['BR', 'PT']) ->orderBy(Metric::Visitors, 'desc') ->limit(50); $rows = Plausible::rows($query); 사이트 관리: Plausible::sites(); Plausible::createSite('example.com', 'America/Sao_Paulo'); Plausible::deleteSite('example.com'); 목표 관리: Plausible::goals(); Plausible::createEventGoal('Signup'); Plausible::deleteGoal(1); 열거형 (Enums) Metric – Visitors, Visits, Pageviews, BounceRate, VisitDuration, Events 등 DateRange – Day, Last7Days, Last30Days, Last12Months, Year, All 등 Dimension – Page, Hostname, Source, Referrer, Device, Browser, Country, City, TimeHour, TimeDay 등 오류 처리 - AuthenticationException: 누락되거나 유효하지 않은 API 키 또는 사이트 ID, 또는 403 응답인 경우 발생합니다. - RateLimitException: HTTP 429 응답인 경우 발생합니다. - PlausibleException: 일반적인 API 실패(상위 예외들의 베이스 클래스)인 경우 발생합니다. 테스트 및 개발 composer test로 테스트 수트를 실행하고, composer format으로 코드를 정렬하며, composer analyse로 정적 분석을 수행합니다. 라이선스 MIT 라이선스에 따라 배포됩니다.